headroomlabs-ai/headroom · error · HeadroomConnectionError

Failed to connect to Headroom at ${this.baseUrl}: ${error}

Error message

Failed to connect to Headroom at ${this.baseUrl}: ${error}

What it means

Error "Failed to connect to Headroom at ${this.baseUrl}: ${error}" thrown in headroomlabs-ai/headroom.

Source

Thrown at sdk/typescript/src/client.ts:531

      // Don't override provider auth headers
      if (!headers["Authorization"] && !headers["x-api-key"]) {
        headers["Authorization"] = `Bearer ${this.apiKey}`;
      }
    }
    if (this.stack && !headers["X-Headroom-Stack"]) {
      headers["X-Headroom-Stack"] = this.stack;
    }

    let response: Response;
    try {
      response = await fetch(url, {
        method: options.method,
        headers,
        body: options.body ? JSON.stringify(options.body) : undefined,
        signal: AbortSignal.timeout(this.timeout),
      });
    } catch (error) {
      throw new HeadroomConnectionError(
        `Failed to connect to Headroom at ${this.baseUrl}: ${error}`,
      );
    }

    if (!response.ok) {
      let errorBody: ProxyErrorResponse | undefined;
      try {
        errorBody = (await response.json()) as ProxyErrorResponse;
      } catch {
        // ignore
      }
      throw mapProxyError(
        response.status,
        errorBody?.error?.type ?? "unknown",
        errorBody?.error?.message ?? `HTTP ${response.status}`,
      );
    }

View on GitHub (pinned to 322425c43b)

Solutions

1. Start the Headroom proxy/server and confirm it listens on ${this.baseUrl}
2. Check for port conflicts or firewall rules blocking the connection
3. Verify the baseUrl passed to the client is correct (scheme, host, port)
4. Inspect ${error} for connection refused vs timeout vs DNS failure

When it happens

Trigger: Raised when the TypeScript client cannot establish a connection to the Headroom server at the configured base URL.

Common situations: See trigger scenarios.

AI-assisted analysis of headroomlabs-ai/headroom@322425c43b (2026-08-15). Data as JSON: /api/errors/1fa636344439de63. Report an issue: GitHub.