What causes "Invalid Context7 base URL: ${raw}" in upstash/context7?

Prefix the value with https:// (e.g. 'myserver.com' -> 'https://myserver.com').

Invalid Context7 base URL

Error message

Invalid Context7 base URL: ${raw}

What it means

Thrown by normalizeDeploymentBaseUrl when the provided deployment URL string cannot be parsed by the URL constructor. The CLI requires a syntactically valid absolute URL for a custom (on-prem) Context7 deployment; anything unparseable is rejected before any network call is made.

Solutions

Prefix the value with https:// (e.g. 'myserver.com' -> 'https://myserver.com').
Re-check the string for typos, spaces, or unexpanded shell variables.
Omit the argument entirely to fall back to DEFAULT_CONTEXT7_BASE_URL.

Example fix

// before
ctx7 setup --url my-onprem.internal

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

Defensive patterns

Strategy: validation

Validate before calling

function isValidDeploymentUrl(raw?: string): boolean {
  if (!raw?.trim()) return true; // falls back to default
  try { new URL(raw.trim()); return true; } catch { return false; }
}

Try / catch

try {
  const dep = resolveSetupDeployment(input);
} catch (e) {
  console.error(`Bad --url value: ${(e as Error).message}. Include the https:// scheme.`);
  process.exitCode = 1;
}

Prevention

Always include the https:// scheme when typing deployment URLs.
Quote URLs in shells to avoid splitting on special characters.
Echo/inspect the variable holding the URL before passing it.

When it happens

Trigger: resolveSetupDeployment(input) / normalizeDeploymentBaseUrl is called with a string that `new URL(raw)` cannot parse — e.g. missing scheme ('myserver.com'), whitespace-only is fine but 'http://foo bar' or ':::' fail.

Common situations: Typing the deployment address without the http(s):// scheme; pasting a URL with stray characters or internal spaces; shell interpolation producing an empty/garbled value in a setup flag or env var.

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/2c946e690a3907a4. Report an issue: GitHub.

Appendix: source

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

import type { AuthOptions } from "./agents.js";
import { DEFAULT_CONTEXT7_BASE_URL } from "../utils/api.js";

const HOSTED_MCP_BASE_URL = "https://mcp.context7.com";

export type SetupDeployment =
  | { kind: "hosted"; baseUrl: typeof DEFAULT_CONTEXT7_BASE_URL }
  | { kind: "custom"; baseUrl: string };
export type CustomSetupDeployment = Extract<SetupDeployment, { kind: "custom" }>;

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;

View on GitHub (pinned to 4416fb855b)