withastro/astro · error · AstroError

ConfigNotFound

ConfigNotFound

Error message

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

What it means

`resolveConfigPath` joins the `--config` argument with the project root and checks existence with `fs.existsSync`; if the file is absent it throws `ConfigNotFound`. This validates the explicitly-passed config path before Astro attempts to load it, giving a precise error instead of a confusing import failure.

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 d081033d5f)

Solutions

1. Verify the file exists at `<root>/<configFile>` (the root is the cwd or the value Astro computes).
2. Run the CLI from the project root so the relative path resolves correctly.
3. Update the npm script / CI command to point at the correct config filename.
4. Drop `--config` to let Astro auto-discover `astro.config.{mjs,ts,js}`.

Example fix

// before
astro dev --config ./config/astro.prod.mjs

// after (fix path or remove flag)
astro dev --config ./config/astro.prod.config.mjs
// or
astro dev

const fs = require('fs'); const path = require('path');
if (configFile && !fs.existsSync(path.join(root, configFile))) {
  throw new Error('Config file not found: ' + configFile);
}

function configExists(root, file) {
  return !file || fs.existsSync(path.join(root, file));
}

When it happens

Trigger: Running `astro dev --config ./astro.config.prod.mjs` (or `build`/`sync`) when that file does not exist relative to the project root. Also triggered by a script/package.json passing a stale `--config` path.

Common situations: Renaming/deleting a config file without updating the npm script; running the CLI from the wrong working directory so the relative path resolves elsewhere; typo in the `--config` value; CI using a config path that exists only in another branch.

Related errors

• Unknown error parsing tsconfig.json or jsconfig.json. Could
• `--ignore-lock` cannot be used together with `--background`.
• [preview] No adapter found.
• CONTENT_TOO_LARGE
• Configured image service is not a local service

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