abhigyanpatwari/GitNexus · error · Error

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

Error message

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

What it means

Thrown by validateBackendUrl() when `new URL(url)` throws — i.e. the input is not a parseable absolute URL (missing protocol, malformed host, stray characters). The raw input is deliberately NOT echoed in the message because it may contain embedded credentials (user:pass@host), which would leak into logs/error surfaces. This is the first of two URL checks; the second (error 11) covers the wrong-protocol case.

Source

Thrown at gitnexus-web/src/services/backend-client.ts:300

// ── Configuration ──────────────────────────────────────────────────────────

let _backendUrl = 'http://localhost:4747';

/**
 * Validate that a backend URL is a safe http:// or https:// origin before
 * storing it as the fetch target base (CodeQL js/client-side-request-forgery).
 *
 * Throws if the URL uses a non-HTTP scheme (e.g. javascript:, data:, file://).
 * All other well-formed http/https URLs are accepted — the client intentionally
 * supports connecting to remote GitNexus servers, not just localhost.
 */
export function validateBackendUrl(url: string): void {
  let parsed: URL;
  try {
    parsed = new URL(url);
  } catch {
    // Do not echo raw input — it may contain credentials.
    throw new Error('Invalid backend URL: must be a well-formed http:// or https:// URL');
  }
  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
    // Use parsed.protocol only (scheme), not the full URL, to avoid leaking credentials.
    throw new Error(`Backend URL must use http:// or https:// (got ${parsed.protocol})`);
  }
}

export const setBackendUrl = (url: string): void => {
  const trimmed = url.replace(/\/$/, '');
  validateBackendUrl(trimmed);
  _backendUrl = trimmed;
};

export const getBackendUrl = (): string => _backendUrl;

/**
 * Normalize a user-entered server URL into a base URL suitable for setBackendUrl().
 * Adds protocol if missing, strips trailing slashes, and strips a trailing /api suffix

View on GitHub (pinned to d540b00184)

Solutions

  1. Run user input through normalizeServerUrl() first — it prepends http:// for localhost/127.0.0.1 and https:// otherwise
  2. Provide a full URL including protocol: 'http://localhost:4747' or 'https://my-server.example.com'
  3. Trim whitespace before validating
  4. If the URL contains credentials, note the error won't echo them — supply a clean origin instead

Example fix

// before — bare host:port, URL constructor throws
setBackendUrl('localhost:4747'); // throws 'Invalid backend URL...'

// after — normalize first, then set
setBackendUrl(normalizeServerUrl('localhost:4747')); // -> 'http://localhost:4747'
Defensive patterns

Strategy: validation

Validate before calling

import { normalizeServerUrl } from './services/backend-client.js';
// normalizeServerUrl prepends a protocol (http for localhost, https otherwise)
// and strips trailing slashes + /api suffix BEFORE setBackendUrl validates
const safe = normalizeServerUrl(userInput);
setBackendUrl(safe); // won't throw 'Invalid backend URL'

Type guard

function isWellFormedUrl(s: string): boolean {
  try { new URL(s); return true; } catch { return false; }
}

Try / catch

try {
  setBackendUrl(input);
} catch (e) {
  if (e instanceof Error && /Invalid backend URL/.test(e.message)) {
    // input didn't parse — try normalizing, or prompt the user
    const normalized = normalizeServerUrl(input);
    setBackendUrl(normalized);
  }
  throw e;
}

Prevention

When it happens

Trigger: Calling setBackendUrl(url) or validateBackendUrl(url) with a value like 'localhost:4747' (no protocol), 'my server', ':4747', an empty string, or any string the URL constructor rejects. Note normalizeServerUrl() exists to prepend a protocol and should be called first for user input.

Common situations: User typed a bare host:port into the server URL field without a protocol; programmatic caller bypassed normalizeServerUrl(); a copy-paste that dropped the scheme; trailing/leading whitespace breaking the URL parser.

Related errors

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