{"record":{"id":"6f40d0a076e7fe48","repo":"withastro/astro","slug":"error-running-cmd-no-command-found","errorCode":null,"errorMessage":"Error running ${cmd} -- no command found.","messagePattern":"Error running (.+?) -- no command found\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/astro/src/cli/index.ts","lineNumber":252,"sourceCode":"\t\t\tconst server = await preview({ flags });\n\t\t\tif (server) {\n\t\t\t\treturn await server.closed(); // keep alive until the server is closed\n\t\t\t}\n\t\t\treturn;\n\t\t}\n\t\tcase 'check': {\n\t\t\tconst { check } = await import('./check/index.js');\n\t\t\tconst checkServer = await check(flags);\n\t\t\tif (flags.watch) {\n\t\t\t\treturn await new Promise(() => {}); // lives forever\n\t\t\t} else {\n\t\t\t\treturn process.exit(typeof checkServer === 'boolean' && checkServer ? 1 : 0);\n\t\t\t}\n\t\t}\n\t}\n\n\t// No command handler matched! This is unexpected.\n\tthrow new Error(`Error running ${cmd} -- no command found.`);\n}\n\n/** The primary CLI action */\nexport async function cli(argv: string[]) {\n\tconst flags = yargs(argv, { boolean: ['global'], alias: { g: 'global' } });\n\tconst cmd = resolveCommand(flags);\n\ttry {\n\t\tawait runCommand(cmd, flags);\n\t} catch (err) {\n\t\tconst { throwAndExit } = await import('./throw-and-exit.js');\n\t\tawait throwAndExit(cmd, err);\n\t}\n}\n","sourceCodeStart":234,"sourceCodeEnd":266,"githubUrl":"https://github.com/withastro/astro/blob/d081033d5fe8e8a68c4bbbad4af9d2deb9c74bca/packages/astro/src/cli/index.ts#L234-L266","documentation":"`runCommand` resolves a CLI command string via `resolveCommand(flags)` and dispatches it through a switch over known command names. This throw is the unreachable default branch — it fires only when the resolved `cmd` is non-empty but matches no `case`. In a healthy install this never happens because `resolveCommand` validates against the supported command list before reaching here.","triggerScenarios":"The switch in `runCommand` falls through without matching any `case` (dev/build/preview/check/add/docs/etc.). Practically only reachable via a corrupt install, a monkeypatched `resolveCommand`, or an internal refactor that added a command to `resolveCommand` without adding its handler.","commonSituations":"A locally patched/forked Astro where new commands were registered in `resolveCommand` but no `case` was added; running against a half-built `dist/` from a partial `pnpm build`; a third-party plugin that overrode internals.","solutions":["Reinstall Astro (`pnpm install` / `npm install astro`) to restore a consistent CLI bundle.","If running from the monorepo, rebuild the astro package: `pnpm -C packages/astro build`.","Run `astro --help` to confirm which commands the installed version advertises and use the documented spelling.","File a bug if the command appears in `--help` but still throws — the dispatch table and resolver are out of sync."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"const KNOWN = new Set(['dev','build','preview','check','add','docs','sync','preferences','info','telemetry','version','help']);\nif (!KNOWN.has(cmd)) throw new Error(`Unsupported command: ${cmd}`);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Run `astro --help` to confirm supported commands for your version.","Keep Astro updated; rebuild from source when patching the monorepo (`pnpm -C packages/astro build`)."],"tags":["cli","unreachable","internal","dispatch"],"backgroundTag":null,"analyzedSha":"d081033d5fe8e8a68c4bbbad4af9d2deb9c74bca","analyzedAt":"2026-08-12T13:37:29.035Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}