withastro/astro · error · Error

Incorrect value for

Error message

Incorrect value for ${key}

What it means

Astro persists preferences (telemetry ok, update checks, first-wizard flags) as JSON with a type marker (string/number/boolean) in per-project (.astro dir) and global preference stores. On read, the deserializer switches on that stored type; the default branch throws `Incorrect value for ${key}` when the stored type is something else - i.e. the preferences file is corrupted, hand-edited, or was written by an incompatible Astro version.

Solutions

  1. Reset the offending preference: `npx astro preferences unset <name>` (or disable/enable it again).
  2. If unset itself fails, delete the store file - project: <root>/.astro/preferences.json, global: the Astro preferences dir in your home directory - Astro recreates it with defaults.
  3. Stop committing or hand-editing the preferences file, and regenerate it after version switches.

Example fix

# before - .astro/preferences.json contains a broken entry
{ "telemetry": { "value": 1, "type": "bool" } } // wrong type marker

# after - reset to a well-formed state
npx astro preferences unset telemetry
# or simply delete the file:
rm .astro/preferences.json
Defensive patterns

Strategy: fallback

Validate before calling

// guard before reading a preference: verify the stored type marker
function isKnownPrefType(t: unknown): t is 'string' | 'number' | 'boolean' {
  return t === 'string' || t === 'number' || t === 'boolean';
}

Try / catch

try {
  const value = astroPreferences.get('telemetry');
} catch {
  // store is corrupt: reset to defaults and continue
  execSync('npx astro preferences unset telemetry', { stdio: 'ignore' });
}

Prevention

When it happens

Trigger: A preferences JSON file where an entry's type field is missing, misspelled, or a non-supported value (e.g. 'object' from a future version); manually editing .astro/preferences.json or the global preferences file; partial writes from a killed process leaving truncated JSON metadata.

Common situations: Checking .astro/preferences.json into version control and merging conflicts badly; switching between very old and new Astro versions on the same machine; scripts or tools rewriting files inside the .astro directory.

Related errors

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

Appendix: source

Thrown at packages/astro/src/preferences/index.ts:78

export function isValidKey(key: string): key is PreferenceKey {
	return dget(DEFAULT_PREFERENCES, key) !== undefined;
}
export function coerce(key: string, value: unknown) {
	const type = typeof dget(DEFAULT_PREFERENCES, key);
	// eslint-disable-next-line @typescript-eslint/switch-exhaustiveness-check
	switch (type) {
		case 'string':
			return value;
		case 'number':
			return Number(value);
		case 'boolean': {
			if (value === 'true' || value === 1) return true;
			if (value === 'false' || value === 0) return false;
			break;
		}
		default:
			throw new Error(`Incorrect value for ${key}`);
	}
	return value as any;
}

export default function createPreferences(
	config: Record<string, any>,
	dotAstroDir: URL,
): AstroPreferences {
	const global = new PreferenceStore(getGlobalPreferenceDir());
	const project = new PreferenceStore(fileURLToPath(dotAstroDir));
	const stores: Record<PreferenceLocation, PreferenceStore> = { global, project };

	return {
		async get(key, { location } = {}) {
			if (!location) return project.get(key) ?? global.get(key) ?? dget(DEFAULT_PREFERENCES, key);
			return stores[location].get(key);
		},
		async set(key, value, { location = 'project', reloadServer = true } = {}) {

View on GitHub (pinned to 52e6c34790)