{"record":{"id":"30603e5fd44ff5a5","repo":"upstash/context7","slug":"api-key-is-required-pass-it-in-the-config-or-set","errorCode":null,"errorMessage":"API key is required. Pass it in the config or set CONTEXT7_API_KEY environment variable.","messagePattern":"API key is required\\. Pass it in the config or set CONTEXT7_API_KEY environment variable\\.","errorType":"exception","errorClass":"Context7Error","httpStatus":null,"severity":"critical","filePath":"packages/sdk/src/client.ts","lineNumber":25,"sourceCode":"} from \"@commands/types\";\nimport { Context7Error } from \"@error\";\nimport { HttpClient } from \"@http\";\nimport { SearchLibraryCommand, GetContextCommand } from \"@commands/index\";\n\nconst DEFAULT_BASE_URL = \"https://context7.com/api\";\nconst API_KEY_PREFIX = \"ctx7sk\";\n\nexport type * from \"@commands/types\";\nexport * from \"@error\";\n\nexport class Context7 {\n  private httpClient: HttpClient;\n\n  constructor(config: Context7Config = {}) {\n    const apiKey = config.apiKey || process.env.CONTEXT7_API_KEY;\n\n    if (!apiKey) {\n      throw new Context7Error(\n        \"API key is required. Pass it in the config or set CONTEXT7_API_KEY environment variable.\"\n      );\n    }\n\n    if (!apiKey.startsWith(API_KEY_PREFIX)) {\n      console.warn(`API key should start with '${API_KEY_PREFIX}'`);\n    }\n\n    this.httpClient = new HttpClient({\n      baseUrl: DEFAULT_BASE_URL,\n      headers: {\n        Authorization: `Bearer ${apiKey}`,\n      },\n      retry: {\n        retries: 5,\n        backoff: (retryCount) => Math.exp(retryCount) * 50,\n      },\n      cache: \"no-store\",","sourceCodeStart":7,"sourceCodeEnd":43,"githubUrl":"https://github.com/upstash/context7/blob/ca15df0443ee770506fc4eb270d1efc71d483933/packages/sdk/src/client.ts#L7-L43","documentation":"Thrown by the Context7 SDK constructor when neither config.apiKey nor the CONTEXT7_API_KEY environment variable is set. It is a hard precondition: the SDK cannot attach an Authorization header without it. A separate (non-fatal) warning is emitted if the key does not start with the 'ctx7sk' prefix.","triggerScenarios":"Calling `new Context7()` or `new Context7({})` while CONTEXT7_API_KEY is unset and no apiKey is passed; env var typo (CONTEXT7_API_KEYS, CONTEXT7_KEY); .env file not loaded in the current process; CI runner without the secret.","commonSituations":"Forgot to add CONTEXT7_API_KEY to .env / not run via a loader; deployed without injecting the secret; renamed the env var; using the SDK in a fresh shell that never sourced the project env.","solutions":["Set CONTEXT7_API_KEY in the environment before constructing the client.","Pass the key explicitly: `new Context7({ apiKey: process.env.MY_KEY })`.","Ensure your .env loader (dotenv etc.) runs before SDK construction.","In CI, add the key as a masked secret and export it in the job env."],"exampleFix":"// before\nconst client = new Context7(); // throws if CONTEXT7_API_KEY unset\n\n// after\nconst client = new Context7({ apiKey: process.env.CONTEXT7_API_KEY });\nif (!process.env.CONTEXT7_API_KEY) {\n  throw new Error(\"Missing CONTEXT7_API_KEY — copy it from the Context7 dashboard.\");\n}","handlingStrategy":"validation","validationCode":"const apiKey = process.env.CONTEXT7_API_KEY;\nif (!apiKey) {\n  throw new Error(\"CONTEXT7_API_KEY is not set. Get one from the Context7 dashboard and export it.\");\n}\nif (!apiKey.startsWith(\"ctx7sk\")) {\n  console.warn(\"API key should start with 'ctx7sk' — the SDK will warn too.\");\n}\nconst client = new Context7({ apiKey });","typeGuard":"function isApiKey(v: unknown): v is string {\n  return typeof v === \"string\" && v.startsWith(\"ctx7sk\");\n}\nconst key = process.env.CONTEXT7_API_KEY;\nif (!isApiKey(key)) {\n  throw new Error(\"CONTEXT7_API_KEY missing or malformed (expected 'ctx7sk...' prefix).\");\n}","tryCatchPattern":"import { Context7Error } from \"@error\";\ntry {\n  const client = new Context7();\n} catch (e) {\n  if (e instanceof Context7Error && /API key is required/.test(e.message)) {\n    throw new Error(\"Missing API key — copy it from the dashboard into CONTEXT7_API_KEY.\");\n  }\n  throw e;\n}","preventionTips":["Load .env (dotenv) before constructing the client.","In CI, inject CONTEXT7_API_KEY as a masked secret in the job environment.","Use the typed isApiKey guard at app startup so the failure surfaces at boot, not deep in a request."],"tags":["config","auth","sdk","initialization","env"],"backgroundTag":null,"analyzedSha":"ca15df0443ee770506fc4eb270d1efc71d483933","analyzedAt":"2026-08-12T13:31:48.440Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}