langfuse/langfuse · error · OutboundUrlValidationError

protocol-not-allowed

protocol-not-allowed

Error message

Only HTTP and HTTPS protocols are allowed

What it means

Thrown by validateLlmConnectionBaseURL when the parsed base URL of an LLM connection uses a protocol other than http: or https: (e.g. ftp:, file:, or a typo like 'httptest://'). The URL is first parsed with parseOutboundUrl, then its protocol is checked against an allowlist before DNS/host validation runs. This protects the server from being coerced into unexpected outbound schemes.

Source

Thrown at packages/shared/src/server/llm/baseUrlValidation.ts:42

  };
}

export async function validateLlmConnectionBaseURL(
  urlString: string,
  whitelist: LlmBaseUrlValidationWhitelist = llmBaseUrlWhitelistFromEnv(),
): Promise<void> {
  const effectiveWhitelist = env.NEXT_PUBLIC_LANGFUSE_CLOUD_REGION
    ? {
        hosts: [],
        ips: [],
        ip_ranges: [],
      }
    : whitelist;

  const url = parseOutboundUrl(urlString);

  if (!["https:", "http:"].includes(url.protocol)) {
    throw new OutboundUrlValidationError(
      "protocol-not-allowed",
      "Only HTTP and HTTPS protocols are allowed",
    );
  }

  await validateOutboundUrlHost({
    url,
    whitelist: effectiveWhitelist,
    logContext: "LLM base URL",
    // Existing LLM validation accepts public IP literals after CIDR checks so
    // custom gateways are not forced through DNS at write time.
    shouldSkipDnsCheckForLiteralIps: true,
  });

  if (env.NEXT_PUBLIC_LANGFUSE_CLOUD_REGION && url.protocol !== "https:") {
    throw new OutboundUrlValidationError(
      "https-required",
      "Only HTTPS base URLs are allowed on Langfuse Cloud",

View on GitHub (pinned to 59d92c7cf3)

Solutions

  1. Fix the baseUrl to start with http:// or https:// (e.g. https://api.openai.com/v1).
  2. If you intended a websocket/gRPC provider, use its HTTP-compatible endpoint instead.
  3. Strip accidental prefixes/suffixes and re-run validation before saving the connection.

Example fix

// before
baseUrl: "https//api.openai.com/v1"
// after
baseUrl: "https://api.openai.com/v1"
Defensive patterns

Strategy: validation

Validate before calling

function hasAllowedProtocol(url: string): boolean {
  try {
    const p = new URL(url.trim()).protocol;
    return p === "https:" || p === "http:";
  } catch {
    return false;
  }
}

Type guard

const isValidLlmBaseUrl = (u: string): boolean =>
  hasAllowedProtocol(u);

Try / catch

catch (e) { if (e instanceof OutboundUrlValidationError && e.code === "protocol-not-allowed") { /* surface to user editing baseUrl */ } else throw e; }

Prevention

When it happens

Trigger: Saving or using an LLM connection whose baseUrl is e.g. 'ftp://example.com/v1', 'file:///etc/passwd', or a malformed string like 'https//api.openai.com/v1' that parses with an unexpected protocol. Reachable via validateBaseURLForWrite (API key routers), fetchSecureLlmUrl, and llmApiKeyRouter.

Common situations: Typo in baseUrl (missing colon), copy-pasting a websocket (ws://) or gRPC endpoint instead of the HTTP endpoint, or leaving a placeholder like 'YOUR_BASE_URL' in config.

Related errors

AI-assisted analysis of langfuse/langfuse@59d92c7cf3 (2026-08-27). Data as JSON: /api/errors/ba8d855086ee0566. Report an issue: GitHub.