withastro/astro · error · AstroError

ConfigNotFound

ConfigNotFound

Error message

Unable to resolve `--config "${configFile}"`. Does the file exist?

What it means

`ConfigNotFound` is thrown by `resolveConfigPath` when you pass `--config <file>` and `path.join(root, configFile)` fails an `fs.existsSync` check. Without `--config`, Astro auto-searches for a config instead and never throws this. Note the path is joined to the project root (or the `--root` directory), not the current working directory.

Solutions

Verify the file exists at `<root>/<configFile>` (e.g. `ls astro.config.prod.ts` from the project root).
Fix the filename or path in the CLI flag or npm script.
Create the missing config file if it was supposed to exist.
Drop `--config` entirely to let Astro auto-discover the default config.

Example fix

# before
astro dev --config astro.config.prod.ts   # file does not exist at root

# after
astro dev --config astro.config.production.ts  # exact filename at project root

Defensive patterns

Strategy: validation

Validate before calling

// Wrapper script around astro CLI calls
import { existsSync } from 'node:fs';
import path from 'node:path';
const cfg = path.resolve(process.cwd(), 'astro.config.prod.ts');
if (!existsSync(cfg)) {
  throw new Error(`Missing config file: ${cfg}`);
}

Prevention

Keep one canonical config filename documented in the repo README or npm scripts.
Add an existence check in CI scripts that pass `--config`.
Remember the path resolves against the project root (`--root`), not the shell's cwd.

When it happens

Trigger: Running `astro dev --config astro.config.prod.ts` (or build/preview/sync) when that file does not exist under the project root; passing a path computed for a different `--root`; typo in the filename.

Common situations: Renamed or deleted config file while CI scripts still reference the old name; config path written relative to the repo root but the command runs with a different `--root`; simple typo.

Understand the failure class

Background: "Config file not found": what it means and how to fix it in docker-sync, Maven, Vagrant, Turborepo and other tools — this error's family across 60 libraries.

Related errors

AI-assisted analysis of withastro/astro@52e6c34790 (2026-08-18). Data as JSON: /api/errors/fdcc2509c0d5086a. Report an issue: GitHub.

Appendix: source

Thrown at packages/astro/src/core/config/config.ts:62

}

interface ResolveConfigPathOptions {
	root: string;
	configFile?: string | false;
	fs: typeof fs;
}

/**
 * Resolve the file URL of the user's `astro.config.js|mjs|ts` file
 */
export async function resolveConfigPath(
	options: ResolveConfigPathOptions,
): Promise<string | undefined> {
	let userConfigPath: string | undefined;
	if (options.configFile) {
		userConfigPath = path.join(options.root, options.configFile);
		if (!options.fs.existsSync(userConfigPath)) {
			throw new AstroError({
				...AstroErrorData.ConfigNotFound,
				message: AstroErrorData.ConfigNotFound.message(options.configFile),
			});
		}
	} else {
		userConfigPath = await search(options.fs, options.root);
	}

	return userConfigPath;
}

async function loadConfig(
	root: string,
	configFile?: string | false,
	fsMod = fs,
): Promise<Record<string, any>> {
	if (configFile === false) return {};

View on GitHub (pinned to 52e6c34790)