upstash/context7 · error · Context7Error

Authentication is required. Pass apiKey or authToken, or…

Error message

Authentication is required. Pass apiKey or authToken, or set CONTEXT7_API_KEY.

What it means

resolveCredential builds the client credential by checking config.apiKey, then config.authToken, then the CONTEXT7_API_KEY environment variable. If none is present it throws Context7Error because every API request requires authentication. The error is deliberate and immediate so misconfigured clients fail before making network calls.

Solutions

1. Pass apiKey in the client config: new Context7Client({ apiKey: 'ctx7sk_...' })
2. Pass an authToken if you authenticate via a bearer token instead
3. Set the CONTEXT7_API_KEY environment variable and ensure your .env is actually loaded (import 'dotenv/config')
4. Verify the variable name is exactly CONTEXT7_API_KEY and that the secret is present in your deployment environment

Example fix

// before
const client = new Context7Client({});
// after
const client = new Context7Client({ apiKey: process.env.CONTEXT7_API_KEY });

const apiKey = config.apiKey ?? process.env.CONTEXT7_API_KEY;
if (!apiKey && !config.authToken) throw new Error('CONTEXT7: no credential configured');

function hasCredential(c: { apiKey?: string; authToken?: string }): boolean {
  return Boolean(c.apiKey || c.authToken || (typeof process !== 'undefined' && process.env?.CONTEXT7_API_KEY));
}

let client;
try {
  client = new Context7Client(config);
} catch (e) {
  if (e instanceof Context7Error && e.message.startsWith('Authentication is required')) {
    console.error('Set CONTEXT7_API_KEY or pass apiKey/authToken');
    process.exit(1);
  }
  throw e;
}

When it happens

Trigger: Constructing the Context7 client with no apiKey and no authToken in the config object while CONTEXT7_API_KEY is unset (or process is unavailable, e.g. in some edge/non-Node runtimes).

Common situations: Forgetting to pass credentials after migrating from an anonymous usage pattern; .env file not loaded (dotenv not initialized); CI/CD missing the CONTEXT7_API_KEY secret; typo like CONTEXT_API_KEY; browser bundle where process.env is undefined.

Understand the failure class

• Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

• API key is required. Pass it in the config or set…
• API key should start with
• authentication_error
• -32001
• Context7UrlError

AI-assisted analysis of upstash/context7@4416fb855b (2026-09-16). Data as JSON: /api/errors/aff0ab7f10a6bdb3. Report an issue: GitHub.

Appendix: source

Thrown at packages/sdk/src/client.ts:151

   */
  async getContext(
    query: string,
    libraryId: string,
    options?: GetContextOptions
  ): Promise<Documentation[] | string> {
    const command = new GetContextCommand(query, libraryId, options);
    return command.exec(this.httpClient);
  }
}

function resolveCredential(config: Context7Config): Credential {
  if (config.apiKey) return { kind: "apiKey", value: config.apiKey };
  if (config.authToken) return { kind: "authToken", value: config.authToken };

  const environmentApiKey = getEnvironmentApiKey();
  if (environmentApiKey) return { kind: "apiKey", value: environmentApiKey };

  throw new Context7Error(
    "Authentication is required. Pass apiKey or authToken, or set CONTEXT7_API_KEY."
  );
}

function getEnvironmentApiKey(): string | undefined {
  return typeof process === "undefined" ? undefined : process.env?.CONTEXT7_API_KEY;
}

function withoutAuthorizationHeader(headers?: Record<string, string>): Record<string, string> {
  return Object.fromEntries(
    Object.entries(headers ?? {}).filter(([name]) => name.toLowerCase() !== "authorization")
  );
}

View on GitHub (pinned to 4416fb855b)