upstash/context7 · error · Context7Error

API key is required. Pass it in the config or set…

Error message

API key is required. Pass it in the config or set CONTEXT7_API_KEY environment variable.

What it means

The `Context7` SDK constructor resolves the API key as `config.apiKey || process.env.CONTEXT7_API_KEY` and throws `Context7Error` when both are falsy. A key that does not start with `ctx7sk` only triggers a console warning, not this throw — only a fully missing key does.

Solutions

1. Pass the key explicitly: `new Context7({ apiKey: 'ctx7sk_...' })`
2. Or `export CONTEXT7_API_KEY=ctx7sk_...` in the environment that runs the process
3. If using dotenv, ensure `import 'dotenv/config'` runs before constructing the client
4. Verify with `process.env.CONTEXT7_API_KEY` logging right before construction

Example fix

// before
import 'dotenv/config';
const client = new Context7(); // throws if .env lacks the key

// after
import 'dotenv/config';
const client = new Context7({ apiKey: process.env.CONTEXT7_API_KEY! });

const apiKey = process.env.CONTEXT7_API_KEY;
if (!apiKey) {
  throw new Error('CONTEXT7_API_KEY is not set — add it to .env or the process environment');
}
const client = new Context7({ apiKey });

function hasApiKey(cfg: { apiKey?: string } | undefined): cfg is { apiKey: string } {
  return Boolean(cfg?.apiKey) || Boolean(process.env.CONTEXT7_API_KEY);
}

When it happens

Trigger: `new Context7()` or `new Context7({})` with CONTEXT7_API_KEY unset; passing `apiKey: ""`; the env var being set in a different shell/PM2/CI context than the process; dotenv loading after construction.

Common situations: Missing `.env` entry or `.env` not loaded before import side effects; CI secret not exposed to the job; deploying with a different user that lacks the env var; key stored under a differently-named variable.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• API key should start with
• Authentication is required. Pass apiKey or authToken, or…
• errorBody.error || errorBody.message || res.statusText
• Request did not return a result
• Request did not return a result

AI-assisted analysis of upstash/context7@80e681a507 (2026-09-08). Data as JSON: /api/errors/30603e5fd44ff5a5. Report an issue: GitHub.

Appendix: source

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

const API_KEY_PREFIX = "ctx7sk";

export type * from "@commands/types";
export type {
  CacheSetting,
  Context7Fetch,
  Context7ResponseMetadata,
  RateLimitMetadata,
  RetryConfig,
} from "@http";
export * from "@error";

export class Context7 {
  private readonly httpClient: HttpClient;

  constructor(config: Context7Config = {}) {
    const apiKey = config.apiKey || getEnvironmentApiKey();

    if (!apiKey) {
      throw new Context7Error(
        "API key is required. Pass it in the config or set CONTEXT7_API_KEY environment variable."
      );
    }

    if (!apiKey.startsWith(API_KEY_PREFIX)) {
      console.warn(`API key should start with '${API_KEY_PREFIX}'`);
    }

    this.httpClient = new HttpClient({
      baseUrl: config.baseUrl ?? DEFAULT_BASE_URL,
      headers: {
        ...withoutAuthorizationHeader(config.headers),
        Authorization: `Bearer ${apiKey}`,
      },
      retry: config.retry,
      cache: config.cache ?? "no-store",
      timeout: config.timeout,

View on GitHub (pinned to 80e681a507)