upstash/context7 · error

Context7 base URL must not contain a query string or…

Error message

Context7 base URL must not contain a query string or fragment

What it means

Thrown by normalizeDeploymentBaseUrl when the URL contains a query string (?) or fragment (#). A deployment base URL must be a clean origin-plus-path root because the CLI appends its own endpoints (/mcp, /api/...) to it.

Solutions

  1. Remove everything from '?' or '#' onward, keeping only scheme://host[:port]/path-root.
  2. Move any parameters (e.g. tokens) into proper configuration instead of the URL.
  3. Omit the argument to use the hosted default.

Example fix

// before
ctx7 setup --url https://my-onprem.internal?token=abc#mcp

// after
ctx7 setup --url https://my-onprem.internal
Defensive patterns

Strategy: validation

Validate before calling

function urlIsClean(raw: string): boolean {
  try {
    const u = new URL(raw);
    return !u.search && !u.hash;
  } catch { return false; }
}

Try / catch

try {
  const dep = resolveSetupDeployment(input);
} catch (e) {
  if ((e as Error).message.includes('query string or fragment')) {
    console.error('Remove ?query and #fragment from the base URL.');
  }
}

Prevention

When it happens

Trigger: normalizeDeploymentBaseUrl receives a URL with url.search or url.hash non-empty, e.g. 'https://host?env=prod' or 'https://host#section'.

Common situations: Copying a URL straight from a browser address bar including tracking params or an anchor; appending an API key as a query parameter.

Understand the failure class

Background: "Invalid URL" errors: why new URL(), URI.parse, and reqwest::Url reject your string — missing scheme, whitespace, and bad path format — this error's family across 39 libraries.

Related errors

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

Appendix: source

Thrown at packages/cli/src/setup/deployment.ts:28

export function normalizeDeploymentBaseUrl(input?: string): string {
  const raw = input?.trim() || DEFAULT_CONTEXT7_BASE_URL;
  let url: URL;

  try {
    url = new URL(raw);
  } catch {
    throw new Error(`Invalid Context7 base URL: ${raw}`);
  }

  if (url.protocol !== "http:" && url.protocol !== "https:") {
    throw new Error("Context7 base URL must use http:// or https://");
  }
  if (url.username || url.password) {
    throw new Error("Context7 base URL must not contain credentials");
  }
  if (url.search || url.hash) {
    throw new Error("Context7 base URL must not contain a query string or fragment");
  }

  url.pathname = url.pathname.replace(/\/+$/, "") || "/";
  const normalized = url.toString().replace(/\/$/, "");
  if (url.pathname.endsWith("/mcp") || url.pathname.endsWith("/api")) {
    throw new Error("Pass the Context7 deployment root, without /mcp or /api");
  }
  return normalized;
}

export function resolveSetupDeployment(input?: string): SetupDeployment {
  const baseUrl = normalizeDeploymentBaseUrl(input);
  return baseUrl === DEFAULT_CONTEXT7_BASE_URL
    ? { kind: "hosted", baseUrl: DEFAULT_CONTEXT7_BASE_URL }
    : { kind: "custom", baseUrl };
}

export function getMcpUrl(deployment: SetupDeployment, auth: AuthOptions): string {

View on GitHub (pinned to 4416fb855b)