musistudio/claude-code-router · error · Error

Provider Base URL must use http or https.

Error message

Provider Base URL must use http or https.

What it means

validateProviderBaseUrl normalizes the base URL (adding a default scheme when missing via providerUrlWithDefaultScheme) and requires the resulting protocol to be http: or https:. Any other scheme — ftp://, ws://, file:// — is rejected because the gateway can only call HTTP endpoints.

Source

Thrown at packages/core/src/contracts/deep-link.ts:471

    }
  }
  return undefined;
}

function boundedString(value: string | undefined, maxLength: number, label: string): string | undefined {
  if (!value) {
    return undefined;
  }
  if (value.length > maxLength) {
    throw new Error(`${label} is too long.`);
  }
  return value;
}

function validateProviderBaseUrl(value: string): void {
  const url = new URL(providerUrlWithDefaultScheme(value));
  if (!["http:", "https:"].includes(url.protocol)) {
    throw new Error("Provider Base URL must use http or https.");
  }
  if (!url.hostname) {
    throw new Error("Provider Base URL is invalid.");
  }
}

function validateManifestUrl(value: string): void {
  const url = new URL(value);
  if (url.protocol !== "https:") {
    throw new Error("Provider manifest URL must use https.");
  }
  if (url.username || url.password) {
    throw new Error("Provider manifest URL cannot include credentials.");
  }
  if (!url.hostname) {
    throw new Error("Provider manifest URL is invalid.");
  }
}

View on GitHub (pinned to 99f24806c6)

Solutions

1. Set base_url to start with http:// or https:// (e.g. https://api.provider.com/v1)
2. For localhost dev use http://localhost:3000/v1 explicitly
3. Double-check the provider docs endpoint — it is an HTTP REST endpoint, not websockets

Example fix

// before
{"base_url":"ws://api.acme.dev/v1"}
// after
{"base_url":"https://api.acme.dev/v1"}

const u = new URL(baseUrl.includes("://") ? baseUrl : `https://${baseUrl}`); if (u.protocol !== "https:" && u.protocol !== "http:") return fixScheme();

const isHttpBaseUrl = (v: string) => {
  try { const p = new URL(/^\w+:\/\//.test(v) ? v : `https://${v}`).protocol; return p === "http:" || p === "https:"; } catch { return false; }
};

try { validateProviderBaseUrl(baseUrl); } catch (e) { if (e instanceof Error && e.message.includes("http or https")) return coerceToHttps(baseUrl); throw e; }

When it happens

Trigger: Passing base_url="ftp://host", "ws://host", or a scheme like "localhost:3000/v1" where the default-scheme logic still yields a non-http protocol.

Common situations: Typos in scheme; copying an ws:// websocket endpoint from provider docs; file:// paths pasted as base URL; custom scheme prefixes like gws://.

Related errors

• Unsupported link protocol.
• Provider Base URL is invalid.
• Unsupported provider protocol: ${value}
• New API provider base URL is missing.
• The CCR artifact endpoint returned a non-media content type.

AI-assisted analysis of musistudio/claude-code-router@99f24806c6 (2026-08-27). Data as JSON: /api/errors/7f8950aa181ac4ae. Report an issue: GitHub.