sindresorhus/got · error · TypeError

Unexpected agent option: ${key}

Error message

Unexpected agent option: ${key}

What it means

Thrown by the `agent` setter when the `agent` option object has a key other than the supported ones (`http`, `https`, `http2`). Got routes requests by protocol and only recognizes those three agent slots, so any other key is rejected to prevent a misconfigured agent from being silently ignored on a redirect to another protocol.

Source

Thrown at source/core/options.ts:1786

			https: new HttpsAgent()
		}
	});
	```
	*/
	get agent(): Agents {
		return this.#internals.agent;
	}

	set agent(value: Agents) {
		assertPlainObject('agent', value);

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

			if (!(key in this.#internals.agent)) {
				throw new TypeError(`Unexpected agent option: ${key}`);
			}

			const validators = key === 'http2'
				? [is.undefined, (v: unknown) => v === false]
				: [is.object, is.undefined, (v: unknown) => v === false];

			// @ts-expect-error - No idea why `value[key]` doesn't work here.
			assertAny(`agent.${key}`, validators, value[key]);
		}

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

	get h2session(): ClientHttp2Session | undefined {

View on GitHub (pinned to e3924aa1e5)

Solutions

1. Use only `http`, `https`, and/or `http2` as keys inside the `agent` object.
2. If you have a single HTTPS agent, pass it as `agent: {https: yourAgent}`.
3. Remove any non-protocol keys from the `agent` object.

Example fix

// before
await got(url, {agent: {httpsAgent: new https.Agent({keepAlive: true})}});
// after
await got(url, {agent: {https: new https.Agent({keepAlive: true})}});

const validAgentKeys = new Set(['http', 'https', 'http2']);
function validateAgent(agent) {
  for (const key of Object.keys(agent ?? {})) {
    if (!validAgentKeys.has(key)) throw new Error(`Unknown agent key: ${key}`);
  }
}

function isAgents(v: unknown): v is {http?: unknown; https?: unknown; http2?: unknown} {
  if (typeof v !== 'object' || v === null) return false;
  return Object.keys(v).every(k => k === 'http' || k === 'https' || k === 'http2' || k === '__proto__');
}

When it happens

Trigger: Calling `got(url, {agent: {ftp: someAgent}})`, `got(url, {agent: {httpsAgent: ...}})` (request/axios naming), or any `agent` object whose keys are not exactly `http`, `https`, or `http2`.

Common situations: Migrating from `request` which used `agent`/`agentOptions` differently; copying an agent config that included a custom key; passing an agent directly instead of wrapping it in `{https: agent}`.

Related errors

• Unexpected option: ${key}
• Unexpected timeout option: ${key}
• Unexpected hook event: ${knownHookEvent}
• Missing hook event: ${knownHookEvent}
• Invalid DNS lookup IP version: ${value as string}

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