sindresorhus/got · error · Error

Cache option `${key}` does not exist

Error message

Cache option `${key}` does not exist

What it means

Thrown by the `cacheOptions` setter when the object has a key that is not a recognized `http-cache-semantics` option. Valid keys are `shared`, `cacheHeuristic`, `immutableMinTimeToLive`, `ignoreCargoCult`. Unknown keys are rejected to prevent silently ineffective cache settings.

Source

Thrown at source/core/options.ts:3162

	get cacheOptions(): CacheOptions {
		return this.#internals.cacheOptions;
	}

	set cacheOptions(value: CacheOptions) {
		assertPlainObject('cacheOptions', value);

		assertAny('cacheOptions.shared', [is.boolean, is.undefined], value.shared);
		assertAny('cacheOptions.cacheHeuristic', [is.number, is.undefined], value.cacheHeuristic);
		assertAny('cacheOptions.immutableMinTimeToLive', [is.number, is.undefined], value.immutableMinTimeToLive);
		assertAny('cacheOptions.ignoreCargoCult', [is.boolean, is.undefined], value.ignoreCargoCult);

		for (const key of Object.keys(value)) {
			if (key === '__proto__') {
				continue;
			}

			if (!(key in this.#internals.cacheOptions)) {
				throw new Error(`Cache option \`${key}\` does not exist`);
			}
		}

		if (this.#merging) {
			safeObjectAssign(this.#internals.cacheOptions, value);
		} else {
			this.#internals.cacheOptions = {...value};
		}
	}

	/**
	Options for the advanced HTTPS API.
	*/
	get https(): HttpsOptions {
		return this.#internals.https;
	}

	set https(value: HttpsOptions) {

View on GitHub (pinned to e3924aa1e5)

Solutions

1. Use only `shared`, `cacheHeuristic`, `immutableMinTimeToLive`, `ignoreCargoCult` in `cacheOptions`.
2. For cache storage use the separate `cache` option, not `cacheOptions`.
3. Check the `${key}` in the message and remove/rename it.

Example fix

// before
await got(url, {cacheOptions: {maxAge: 600}});
// after
await got(url, {cacheOptions: {immutableMinTimeToLive: 600_000}});

const validCacheOptionKeys = new Set(['shared','cacheHeuristic','immutableMinTimeToLive','ignoreCargoCult']);
function validateCacheOptions(co) {
  for (const k of Object.keys(co ?? {})) {
    if (!validCacheOptionKeys.has(k)) throw new Error(`Unknown cacheOptions key: ${k}`);
  }
}

import type {CacheOptions} from 'got';
function isCacheOptions(v: unknown): v is CacheOptions {
  if (typeof v !== 'object' || v === null) return false;
  return Object.keys(v).every(k => ['shared','cacheHeuristic','immutableMinTimeToLive','ignoreCargoCult','__proto__'].includes(k));
}

When it happens

Trigger: Calling `got(url, {cacheOptions: {maxAge: 600}})` or any `cacheOptions` key outside the four supported ones. Passing top-level cache keys here instead of via the `cache` option also triggers it.

Common situations: Confusing `cacheOptions` (cache *semantics* tuning) with the `cache` option (the storage adapter); copying HTTP cache header names into `cacheOptions`.

Related errors

• Unexpected option: ${key}
• Unexpected agent option: ${key}
• Unexpected timeout option: ${key}
• Unexpected hook event: ${knownHookEvent}
• Missing hook event: ${knownHookEvent}

AI-assisted analysis of sindresorhus/got@e3924aa1e5 (2026-08-03). Data as JSON: /data/errors/510399e742be81dd.json. Report an issue: GitHub.