{"id":"17a494c86ff0340d","repo":"sindresorhus/got","slug":"unexpected-agent-option-key","errorCode":null,"errorMessage":"Unexpected agent option: ${key}","messagePattern":"Unexpected agent option: (.+?)","errorType":"validation","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"source/core/options.ts","lineNumber":1786,"sourceCode":"\t\t\thttps: new HttpsAgent()\n\t\t}\n\t});\n\t```\n\t*/\n\tget agent(): Agents {\n\t\treturn this.#internals.agent;\n\t}\n\n\tset agent(value: Agents) {\n\t\tassertPlainObject('agent', value);\n\n\t\tfor (const key of Object.keys(value)) {\n\t\t\tif (key === '__proto__') {\n\t\t\t\tcontinue;\n\t\t\t}\n\n\t\t\tif (!(key in this.#internals.agent)) {\n\t\t\t\tthrow new TypeError(`Unexpected agent option: ${key}`);\n\t\t\t}\n\n\t\t\tconst validators = key === 'http2'\n\t\t\t\t? [is.undefined, (v: unknown) => v === false]\n\t\t\t\t: [is.object, is.undefined, (v: unknown) => v === false];\n\n\t\t\t// @ts-expect-error - No idea why `value[key]` doesn't work here.\n\t\t\tassertAny(`agent.${key}`, validators, value[key]);\n\t\t}\n\n\t\tif (this.#merging) {\n\t\t\tsafeObjectAssign(this.#internals.agent, value);\n\t\t} else {\n\t\t\tthis.#internals.agent = {...value};\n\t\t}\n\t}\n\n\tget h2session(): ClientHttp2Session | undefined {","sourceCodeStart":1768,"sourceCodeEnd":1804,"githubUrl":"https://github.com/sindresorhus/got/blob/e3924aa1e53a6ca3eb93a43618ce532442a89b40/source/core/options.ts#L1768-L1804","documentation":"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.","triggerScenarios":"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`.","commonSituations":"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}`.","solutions":["Use only `http`, `https`, and/or `http2` as keys inside the `agent` object.","If you have a single HTTPS agent, pass it as `agent: {https: yourAgent}`.","Remove any non-protocol keys from the `agent` object."],"exampleFix":"// before\nawait got(url, {agent: {httpsAgent: new https.Agent({keepAlive: true})}});\n// after\nawait got(url, {agent: {https: new https.Agent({keepAlive: true})}});","handlingStrategy":"type-guard","validationCode":"const validAgentKeys = new Set(['http', 'https', 'http2']);\nfunction validateAgent(agent) {\n  for (const key of Object.keys(agent ?? {})) {\n    if (!validAgentKeys.has(key)) throw new Error(`Unknown agent key: ${key}`);\n  }\n}","typeGuard":"function isAgents(v: unknown): v is {http?: unknown; https?: unknown; http2?: unknown} {\n  if (typeof v !== 'object' || v === null) return false;\n  return Object.keys(v).every(k => k === 'http' || k === 'https' || k === 'http2' || k === '__proto__');\n}","tryCatchPattern":null,"preventionTips":["Always wrap agents as `{https: agent}` / `{http: agent}`.","Never reuse agent-config objects from `request`/axios verbatim.","Add a unit test asserting only http/https/http2 keys survive."],"tags":["options","agent","validation","config"],"analyzedSha":"e3924aa1e53a6ca3eb93a43618ce532442a89b40","analyzedAt":"2026-08-03T19:22:24.770Z","schemaVersion":2}