withastro/astro · error · Error

Error running ${cmd} -- no command found.

Error message

Error running ${cmd} -- no command found.

What it means

`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.

Source

Thrown at packages/astro/src/cli/index.ts:252

			const server = await preview({ flags });
			if (server) {
				return await server.closed(); // keep alive until the server is closed
			}
			return;
		}
		case 'check': {
			const { check } = await import('./check/index.js');
			const checkServer = await check(flags);
			if (flags.watch) {
				return await new Promise(() => {}); // lives forever
			} else {
				return process.exit(typeof checkServer === 'boolean' && checkServer ? 1 : 0);
			}
		}
	}

	// No command handler matched! This is unexpected.
	throw new Error(`Error running ${cmd} -- no command found.`);
}

/** The primary CLI action */
export async function cli(argv: string[]) {
	const flags = yargs(argv, { boolean: ['global'], alias: { g: 'global' } });
	const cmd = resolveCommand(flags);
	try {
		await runCommand(cmd, flags);
	} catch (err) {
		const { throwAndExit } = await import('./throw-and-exit.js');
		await throwAndExit(cmd, err);
	}
}

View on GitHub (pinned to d081033d5f)

Solutions

1. Reinstall Astro (`pnpm install` / `npm install astro`) to restore a consistent CLI bundle.
2. If running from the monorepo, rebuild the astro package: `pnpm -C packages/astro build`.
3. Run `astro --help` to confirm which commands the installed version advertises and use the documented spelling.
4. File a bug if the command appears in `--help` but still throws — the dispatch table and resolver are out of sync.

const KNOWN = new Set(['dev','build','preview','check','add','docs','sync','preferences','info','telemetry','version','help']);
if (!KNOWN.has(cmd)) throw new Error(`Unsupported command: ${cmd}`);

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Unknown error parsing tsconfig.json or jsconfig.json. Could
• ${integration} does not appear to be a valid package name!
• No problem! Find our official integrations at https://astro.
• Unable to fetch ${integration}. Does the package exist?
• ${packageName} doesn't appear to be an integration or an ada

AI-assisted analysis of withastro/astro@d081033d5f (2026-08-12). Data as JSON: /api/errors/6f40d0a076e7fe48. Report an issue: GitHub.