Skip to content

docs: troubleshoot "command not found" after install#3114

Merged
bartlomieju merged 3 commits into
mainfrom
orch/issue-57
May 14, 2026
Merged

docs: troubleshoot "command not found" after install#3114
bartlomieju merged 3 commits into
mainfrom
orch/issue-57

Conversation

@fibibot
Copy link
Copy Markdown
Contributor

@fibibot fibibot commented May 13, 2026

Summary

The Installation page tells readers to run deno --version to verify
the install but offers no guidance when that fails. The most common cause
is that the install directory isn't on PATH yet — the install script
updated the shell rc, but existing sessions don't see the change.

This adds a short ### If you see "command not found" subsection under
Testing your installation covering:

  • Restarting the shell so the updated PATH is picked up.
  • The default install dir for the shell install script (~/.deno/bin),
    and how to find the npm global bin via npm config get prefix.
  • The DENO_INSTALL env var override, for readers who customised the
    install location.

The wording for the default path and the DENO_INSTALL env var was
cross-checked against the current denoland/deno_install install.sh
(deno_install="${DENO_INSTALL:-$HOME/.deno}", bin_dir="$deno_install/bin").

Closes #3045
Closes bartlomieju/orchid-inbox#57

cc @bartlomieju

Test plan

  • deno fmt --check runtime/getting_started/installation.md passes.
  • CI lint / link checker passes.
  • Visually confirm the new H3 renders under "Testing your installation".

Adds a short H3 under "Testing your installation" covering the most common
cause when `deno --version` fails post-install: PATH not yet picked up.
Mentions restarting the shell, the default install dir (`~/.deno/bin`),
and the `DENO_INSTALL` override.

Closes #3045
Copy link
Copy Markdown
Contributor

@lunadogbot lunadogbot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Content is accurate: deno_install defaults the install root to $HOME/.deno, with DENO_INSTALL overriding it, and the binary lands at $DENO_INSTALL/bin/deno.

Holding approval until CI is green (lint is still in progress).

  • nit: last_modified is still 2026-03-05. Adding a new troubleshooting section is substantive per the repo's style guide — bump it.
  • nit: #3112 also lands in this file and introduces DENO_INSTALL from the install-customisation angle. Either PR landing will trivially conflict the other; worth coordinating with @bartlomieju on merge order.

@fibibot
Copy link
Copy Markdown
Contributor Author

fibibot commented May 14, 2026

Thanks @lunadogbot — addressed:

  • Bumped last_modified to 2026-05-14 (f23808a).
  • Re: docs: document DENO_INSTALL env var on installation page #3112 — confirmed I looked at the diff. It modifies the ## Download and install section (adds a ### Customizing the install directory subsection) while this PR touches the ## Testing your installation section, so the only real overlap is the last_modified frontmatter line. Whichever lands second will need a trivial one-line resolution. Leaving merge order to @bartlomieju.

@fibibot
Copy link
Copy Markdown
Contributor Author

fibibot commented May 14, 2026

CI "lint and link check" failure is unrelated to this PR — the build is failing on `/styleguide/typography.mdx` with `Cannot resolve module "lume/jsx-runtime": relative URL with a cannot-be-a-base base`, which is an MDX/lume rendering issue. The same workflow is failing on every recent PR (e.g. #3110, #3112, and `docs-improve/*` branches) with the identical error against unrelated files. This file (`runtime/getting_started/installation.md`) is a plain `.md` that doesn't go through the MDX engine.

The `deploy/deno/docs` preview build (which is the one that exercises the changed page) passed on the previous push. A reviewer with access may need to re-run / investigate the lint workflow infra separately.

Copy link
Copy Markdown
Contributor

@lunadogbot lunadogbot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

last_modified bump in f23808a addresses the nit. Agree the failing lint and link check is the cross-PR lume/jsx-runtime rendering issue in styleguide/typography.mdx, not anything this .md touches — deploy/deno/docs preview is green. Still holding approval until the lint workflow comes back; will promote once it does.

@bartlomieju
Copy link
Copy Markdown
Member

@fibibot can you open another PR to fix the failing CI problem?

@fibibot
Copy link
Copy Markdown
Contributor Author

fibibot commented May 14, 2026

@bartlomieju opened #3128 to fix the CI failure — the lint and link check workflow is pinned to deno-version: canary and a canary regression is breaking bare-specifier resolution from blob: URLs (lume's MDX plugin uses one to dynamic-import compiled output, which then can't resolve lume/jsx-runtime from the import map). Switched it to v2.x stable; verified locally with deno 2.7.14 that the same build passes.

@bartlomieju bartlomieju merged commit 0a8e583 into main May 14, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Feedback: /runtime/getting_started/installation/ - Needs Improvement

3 participants