withastro/astro · warning · Error

Incorrect value for ${key}

Error message

Incorrect value for ${key}

What it means

When deserializing a stored preference, Astro coerces the stored string to the preference's declared type via a switch. It handles `'string'`, `'number'`, and `'boolean'` (boolean accepts `'true'`/`1` and `'false'`/`0`). Any other type, or a boolean value that isn't one of those four accepted literals, falls through to the `default` branch and throws a plain `Incorrect value for ${key}` Error.

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

Solutions

1. Reset the offending preference by deleting its entry (or the whole preferences store) so Astro re-creates it with a valid value.
2. Ensure boolean preferences store only `'true'`/`'false'`/`1`/`0`; for other types use string or number.
3. Avoid hand-editing the preferences file; use the preferences API.

Example fix

// before — manually edited .astro/preferences.json has
// { "featureFlags.x": { type: "boolean", value: "yes" } }  -> throws

// after — valid boolean literal
// { "featureFlags.x": { type: "boolean", value: "true" } }

function isValidStoredBoolean(value) {
  return value === 'true' || value === 'false' || value === 1 || value === 0;
}
function isValidPrefType(type) {
  return type === 'string' || type === 'number' || type === 'boolean';
}

function isValidPrefEntry(entry) {
  return entry &&
    ['string','number','boolean'].includes(entry.type) &&
    (entry.type !== 'boolean' || ['true','false',1,0].includes(entry.value));
}

null

When it happens

Trigger: A preference declared with a type other than string/number/boolean, or a boolean preference whose stored value is something other than `'true'`, `'false'`, `1`, or `0` (e.g. corrupted store, manually edited `.astro` preferences file).

Common situations: Manually editing the `.astro/preferences.json` (or global preferences) file and writing an invalid boolean like `'yes'` or `1.0`; a preferences schema entry with an unsupported type field; corruption from a partial write or version downgrade.

Related errors

• BAD_REQUEST
• CONTENT_TOO_LARGE
• ActionsReturnedInvalidDataError
• Configured image service is not a local service
• Configured image service is not a local service

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