upstash/context7 · critical · Context7Error

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

Error message

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

What it means

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.

Source

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

} from "@commands/types";
import { Context7Error } from "@error";
import { HttpClient } from "@http";
import { SearchLibraryCommand, GetContextCommand } from "@commands/index";

const DEFAULT_BASE_URL = "https://context7.com/api";
const API_KEY_PREFIX = "ctx7sk";

export type * from "@commands/types";
export * from "@error";

export class Context7 {
  private httpClient: HttpClient;

  constructor(config: Context7Config = {}) {
    const apiKey = config.apiKey || process.env.CONTEXT7_API_KEY;

    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: DEFAULT_BASE_URL,
      headers: {
        Authorization: `Bearer ${apiKey}`,
      },
      retry: {
        retries: 5,
        backoff: (retryCount) => Math.exp(retryCount) * 50,
      },
      cache: "no-store",

View on GitHub (pinned to ca15df0443)

Solutions

1. Set CONTEXT7_API_KEY in the environment before constructing the client.
2. Pass the key explicitly: `new Context7({ apiKey: process.env.MY_KEY })`.
3. Ensure your .env loader (dotenv etc.) runs before SDK construction.
4. In CI, add the key as a masked secret and export it in the job env.

Example fix

// before
const client = new Context7(); // throws if CONTEXT7_API_KEY unset

// after
const client = new Context7({ apiKey: process.env.CONTEXT7_API_KEY });
if (!process.env.CONTEXT7_API_KEY) {
  throw new Error("Missing CONTEXT7_API_KEY — copy it from the Context7 dashboard.");
}

const apiKey = process.env.CONTEXT7_API_KEY;
if (!apiKey) {
  throw new Error("CONTEXT7_API_KEY is not set. Get one from the Context7 dashboard and export it.");
}
if (!apiKey.startsWith("ctx7sk")) {
  console.warn("API key should start with 'ctx7sk' — the SDK will warn too.");
}
const client = new Context7({ apiKey });

function isApiKey(v: unknown): v is string {
  return typeof v === "string" && v.startsWith("ctx7sk");
}
const key = process.env.CONTEXT7_API_KEY;
if (!isApiKey(key)) {
  throw new Error("CONTEXT7_API_KEY missing or malformed (expected 'ctx7sk...' prefix).");
}

import { Context7Error } from "@error";
try {
  const client = new Context7();
} catch (e) {
  if (e instanceof Context7Error && /API key is required/.test(e.message)) {
    throw new Error("Missing API key — copy it from the dashboard into CONTEXT7_API_KEY.");
  }
  throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Failed to fetch user info
• Request did not return a result
• Request did not return a result
• query and libraryName are required
• Request did not return a result

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