What causes "Invalid LLM base URL: must be a well-formed http:// or https:// URL" in abhigyanpatwari/GitNexus?

Ensure the base URL includes a valid `http://` or `https://` scheme (https is preferred for remote endpoints).

abhigyanpatwari/GitNexus · warning · Error

Invalid LLM base URL: must be a well-formed http:// or https

Error message

Invalid LLM base URL: must be a well-formed http:// or https:// URL

What it means

Thrown by `validateLLMBaseUrl` when `new URL(baseUrl)` throws — the supplied LLM base URL is not a parseable URL at all. The raw input is deliberately excluded from the error message because it may contain embedded credentials (e.g., `https://user:pass@host`), and echoing it would leak secrets into logs or error reports.

Source

Thrown at gitnexus/src/core/wiki/llm-client.ts:243

 *  - file://, data:, javascript:, and any other non-HTTP scheme
 *  - http:// aimed at non-loopback hosts unless explicitly allowlisted
 *    (avoids SSRF against internal networks by default)
 *
 * Throws with a descriptive message on validation failure so callers surface a
 * clear error rather than an opaque network error.
 */
export function validateLLMBaseUrl(
  baseUrl: string,
  allowedInsecureHttpHosts: readonly string[] = parseLLMAllowedInsecureHttpHosts(
    process.env[LLM_ALLOW_INSECURE_CONNECTION_ENV],
  ),
): void {
  let parsed: URL;
  try {
    parsed = new URL(baseUrl);
  } catch {
    // Do not include the raw input in the message — it may contain credentials.
    throw new Error('Invalid LLM base URL: must be a well-formed http:// or https:// URL');
  }

  if (!['https:', 'http:'].includes(parsed.protocol)) {
    // Use parsed.protocol only (scheme), not the full URL, to avoid leaking credentials.
    throw new Error(`LLM base URL must use http:// or https:// (got ${parsed.protocol})`);
  }

  if (parsed.protocol === 'http:') {
    // Node's URL parser preserves IPv6 brackets in hostname (e.g. "[::1]"),
    // so strip them before comparing to bare address literals.
    const host = parsed.hostname.toLowerCase().replace(/^\[|\]$/g, '');
    const allowedHosts = new Set(allowedInsecureHttpHosts.map(normalizeAllowedInsecureHttpHost));
    if (host !== 'localhost' && host !== '127.0.0.1' && host !== '::1' && !allowedHosts.has(host)) {
      // Use parsed.origin (scheme+host+port, no credentials) instead of the full URL.
      throw new Error(
        `Insecure http:// LLM base URLs are only allowed for localhost/127.0.0.1 ` +
          `or hosts listed by --allow-insecure-connection / ${LLM_ALLOW_INSECURE_CONNECTION_ENV}. ` +
          `Use https:// for remote endpoints (got ${parsed.origin})`,

View on GitHub (pinned to d540b00184)

Solutions

Ensure the base URL includes a valid `http://` or `https://` scheme (https is preferred for remote endpoints).
Verify there are no unencoded special characters or spaces in the URL.
If the URL contains credentials, use standard `user:pass@host` URL encoding — the validation accepts it but never echoes it back.
Test the URL with `new URL(yourUrl)` in a Node REPL to confirm it parses.

Example fix

# before
export GITNEXUS_LLM_BASE_URL=api.openai.com/v1
gitnexus wiki
# error: Invalid LLM base URL: must be a well-formed http:// or https:// URL
# after
export GITNEXUS_LLM_BASE_URL=https://api.openai.com/v1
gitnexus wiki

Defensive patterns

Strategy: validation

Validate before calling

// Validate the base URL before initializing the LLM client:
import { validateLLMBaseUrl } from './wiki/llm-client.js';
try {
  validateLLMBaseUrl(process.env.GITNEXUS_LLM_BASE_URL!);
} catch (err) {
  console.error('Invalid LLM base URL:', (err as Error).message);
  process.exit(1);
}

Type guard

const isValidBaseUrl = (url: string): boolean => {
  try { new URL(url); return true; } catch { return false; }
};

Try / catch

try {
  validateLLMBaseUrl(baseUrl);
} catch (err) {
  if (err instanceof Error && err.message.includes('well-formed http:// or https:// URL')) {
    console.error('Ensure GITNEXUS_LLM_BASE_URL includes the scheme (https://...).');
  }
  throw err;
}

Prevention

Always include the scheme in `GITNEXUS_LLM_BASE_URL` (`https://api.openai.com/v1`).
Never embed credentials in the URL string visible to logs — use headers if possible.
Test the URL with `new URL(url)` in a Node REPL before setting it as an env var.

When it happens

Trigger: `validateLLMBaseUrl(baseUrl)` is called (at LLM client initialization or wiki generation), and `new URL(baseUrl)` throws a TypeError. The input is structurally invalid as a URL: missing protocol, unencoded spaces, malformed authority, etc.

Common situations: `GITNEXUS_LLM_BASE_URL` is set without a protocol (`api.example.com/v1`); contains unencoded spaces; has a typo in the scheme (`htp://`); is an empty string; or was constructed by string concatenation that produced an invalid URL.

Related errors

AI-assisted analysis of abhigyanpatwari/GitNexus@d540b00184 (2026-08-12). Data as JSON: /api/errors/1b5b152594f21e44. Report an issue: GitHub.