Srihari Sriraman shared in

Public

Resolved OpenAI regional hostname errorPublic

Agent

Model

Claude Opus 4.5 (latest)

Started

Jan 29, 12:35 AM

Messages74

Downloads0

Summary

Closed, Completed

Understand
Analyzed GitHub issue and related code.
Understand
Edit
Updated documentation with correct URL format.
Edit
Verify
Commented on issue explaining user error and fix.
Verify

Analyze GitHub issue(s): https://github.com/badlogic/pi-mono/issues/956

For each issue:

Read the issue in full, including all comments and linked issues/PRs.
For bugs:
- Ignore any root cause analysis in the issue (likely wrong)
- Read all related code files in full (no truncation)
- Trace the code path and identify the actual root cause
- Propose a fix
For feature requests:
- Read all related code files in full (no truncation)
- Propose the most concise implementation approach
- List affected files and changes needed

Do NOT implement unless explicitly asked. Analyze and propose only.

Let me understand the issue:

OpenAI now has regional API endpoints (e.g., us.api.openai.com for US data residency)
When a user has a US data residency API key, they get a 401 error telling them to use us.api.openai.com
The user tried setting a custom baseUrl in ~/.pi/agent/models.json, but that resulted in an empty/garbage response

I need to:

Check how the OpenAI provider handles baseUrl
See what the models.json configuration format looks like
Find out how provider options are merged/applied

Let me look at the relevant code files.

Let me read the relevant OpenAI provider code and understand how base URLs are handled:

Readopenai-responses.ts

Readmodel-registry.ts

Readconfig.ts

I can see the issue now. Looking at the code flow:

In model-registry.ts, when loading custom models from models.json, the loadBuiltInModels function applies the override's baseUrl to models.
The issue is the user is setting:

This is an "override-only" config (no custom models defined). Looking at loadBuiltInModels:

typescript

const override = overrides.get(provider);if (!override) return models;
// Apply baseUrl/headers override to all models of this providerconst resolvedHeaders = resolveHeaders(override.headers);return models.map((m) => ({    ...m,    baseUrl: override.baseUrl ?? m.baseUrl,    headers: resolvedHeaders ? { ...m.headers, ...resolvedHeaders } : m.headers,}));

This looks correct. Let me check how the OpenAI client uses model.baseUrl in openai-responses.ts:

The problem is that model.baseUrl is being used, but for OpenAI, there's a default baseUrl that is probably https://api.openai.com/v1. But when the user sets https://us.api.openai.com, they're missing the /v1 path segment!

Let me verify the OpenAI models to see what their default baseUrl is:

Let me check the OpenAI models configuration to see what the default baseUrl looks like:

Readmodels.generated.ts100 lines

I found the issue. The default OpenAI baseUrl is https://api.openai.com/v1. When the user sets baseUrl to https://us.api.openai.com, they're missing the /v1 path.

The user should be using https://us.api.openai.com/v1 instead of https://us.api.openai.com.

The "empty response" the user got when they set the wrong URL is likely because they hit OpenAI's homepage or another endpoint that returns HTML (not JSON). The itle></head> and /center> snippets in the output appear to be fragments of an HTML response being incorrectly interpreted.

There are a couple of solutions:

Document the correct URL format: Users need to include /v1 in their baseUrl.
Auto-append /v1: This could be error-prone since some OpenAI-compatible APIs might not use /v1.
Better error handling: The streaming code should detect when it receives HTML instead of JSON and provide a clearer error message.

Let me verify this is the issue by checking what the OpenAI SDK does with baseURL:

Now I understand the issue. Let me verify the OpenAI SDK behavior and check if there's any documentation for the models.json format:

Readmodels.md

Now I see the issue clearly. The documentation shows this example for overriding a built-in provider:

So when the user tried:

The problem is they forgot the /v1 path. The correct value should be:

This is documented correctly (the examples all show /v1 suffix), but the user missed it.

The second issue is that when the wrong URL is used (https://us.api.openai.com without /v1), the user gets garbage output (itle></head> and /center>) instead of a clear error. This is because the OpenAI SDK is hitting an HTML page and the code isn't properly detecting/handling that the response is HTML instead of JSON.

Let me verify this by looking at how the streaming response is processed.

Let me check how the OpenAI response streaming handles error cases:

Readopenai-responses-shared.ts

Looking at the code, the issue is that when the user sets baseUrl to https://us.api.openai.com (without /v1), the OpenAI SDK likely hits an HTML page (like a landing page or error page). When the SDK tries to parse this as a streaming response, it gets garbage.

The error handling is present in the processResponsesStream function for event.type === "error" and event.type === "response.failed", but if the response is HTML, it never generates proper SSE events. Instead, the OpenAI SDK might be trying to process garbage as SSE data.

Let me check what the issue reporter saw. They got garbage output that looks like HTML fragments (itle></head> and /center>). This is because:

The URL https://us.api.openai.com (without /v1) returns HTML
The OpenAI SDK tries to parse this as a streaming response
The HTML content ends up being streamed as if it were text deltas

The root cause is that the user needs to use https://us.api.openai.com/v1 (with /v1).

But we should consider:

User error: The documentation is correct, the user just missed the /v1
Missing validation: When baseUrl doesn't end with /v1, we could warn or auto-fix
Poor error handling: When receiving HTML instead of SSE, we should detect and error clearly

Let me see if there's an environment variable for OpenAI base URL that we should support:

Readenv-api-keys.ts

Now I have the full picture. Let me analyze this issue:

Root Cause Analysis

Issue: OpenAI now supports regional API endpoints (e.g., us.api.openai.com for US data residency). Users with US data residency API keys get a 401 error when hitting the default api.openai.com.

User's attempt: The user tried to override the OpenAI baseUrl via ~/.pi/agent/models.json:

Problems:

The user forgot the /v1 path suffix. OpenAI models have baseUrl: "https://api.openai.com/v1", so the override should be https://us.api.openai.com/v1.
When using the wrong URL (without /v1), the response is HTML instead of SSE data. The streaming code doesn't detect this and just passes along garbage text.

Proposed Solution

There are a few approaches:

Option A: Documentation fix only

Just update docs/models.md to explicitly mention the /v1 suffix for OpenAI regional endpoints. This is the simplest but least user-friendly.

Option B: Add OPENAI_BASE_URL environment variable support

OpenAI's official SDK already supports OPENAI_BASE_URL environment variable. Adding support for this would let users set OPENAI_BASE_URL=https://us.api.openai.com/v1 in their environment.

Option C: Better error handling for HTML responses

Detect when a response is HTML instead of SSE data and throw a meaningful error like "Received HTML instead of API response. Check your baseUrl configuration."

Option D: Auto-append `/v1` when missing

This is risky because some OpenAI-compatible APIs might not use /v1.

I think combining Options B and C makes the most sense. Adding environment variable support for OPENAI_BASE_URL aligns with how the official SDK works and gives users a cleaner way to configure regional endpoints. Simultaneously, improving error detection to catch HTML responses and surface a helpful message would prevent silent failures when configuration is wrong. The implementation would involve updating the OpenAI provider to check for the environment variable first, then fall back to model configuration, and adding validation in the response handler to identify and report malformed responses.

Let me check the OpenAI completions provider as well to see how it handles baseURL:

Readopenai-completions.ts

I see that both openai-responses.ts and openai-completions.ts use model.baseUrl directly when creating the OpenAI client:

typescript

return new OpenAI({    apiKey,    baseURL: model.baseUrl,    dangerouslyAllowBrowser: true,    defaultHeaders: headers,});```
The issue is clear:
1. User sets `baseUrl: "https://us.api.openai.com"` (missing `/v1`)2. The OpenAI SDK hits `https://us.api.openai.com/chat/completions` (or similar) which returns HTML (404 or landing page)3. The SDK tries to parse this as SSE data, resulting in garbage output
## Summary of Analysis
**Issue**: OpenAI has regional endpoints (`us.api.openai.com`) for US data residency. Users with US data residency API keys get 401 errors on the default global endpoint.
**User's attempted fix**: Setting `baseUrl: "https://us.api.openai.com"` in models.json, which is **missing the `/v1` suffix**.
**Result**: The request hits an HTML page instead of the API, producing garbage output.
**Root cause**: User error (missing `/v1`), but the documentation doesn't explicitly mention OpenAI regional endpoints or the requirement for the `/v1` suffix when overriding OpenAI's baseUrl.
## Proposed Fix
1. **Documentation update** in `docs/models.md`: Add a specific example for OpenAI regional endpoints showing the correct URL format (`https://us.api.openai.com/v1`).
2. **(Optional) Add `OPENAI_BASE_URL` environment variable support**: This is the standard way the official OpenAI SDK supports custom base URLs. Users could then just set `OPENAI_BASE_URL=https://us.api.openai.com/v1` without needing models.json.

3. I could also add validation to detect HTML responses—if the response starts with `<!DOCTYPE` or `<html`, throw a descriptive error message pointing users to verify their baseUrl includes `/v1`. This would catch the issue immediately rather than producing garbled output.
## Files to Modify
For the minimal fix (documentation only):- `packages/coding-agent/docs/models.md`: Add OpenAI regional endpoint example
For a more complete solution:- `packages/ai/src/providers/openai-responses.ts`: Check `OPENAI_BASE_URL` env var and add HTML detection- `packages/ai/src/providers/openai-completions.ts`: Apply the same changes- `packages/coding-agent/src/cli/args.ts`: Document the `OPENAI_BASE_URL` variable- `packages/ai/README.md`: Add documentation for `OPENAI_BASE_URL`- `packages/coding-agent/docs/models.md`: Include regional endpoint examples

Issue Analysis: #956 - OpenAI Regional Hostname Error

Summary

Users with OpenAI projects configured for US data residency get a 401 error:

"Attempted to access resource with incorrect regional hostname. Please make your request to us.api.openai.com"

The user attempted to fix this by setting baseUrl in models.json, but used the wrong URL format.

Root Cause

User error with missing path suffix. The user configured:

But the correct configuration requires the /v1 path:

OpenAI models have baseUrl: "https://api.openai.com/v1" by default. When the user overrides without /v1, the OpenAI SDK hits https://us.api.openai.com/chat/completions which returns an HTML error page. The streaming code then displays HTML fragments as text (the itle></head> and /center> garbage the user saw).

Proposed Fix

Two-part solution:

1. Documentation update (essential): Add explicit example for OpenAI regional endpoints in docs/models.md

2. Environment variable support (nice-to-have): Support OPENAI_BASE_URL like the official OpenAI SDK does, allowing users to set OPENAI_BASE_URL=https://us.api.openai.com/v1 as an alternative to models.json

Files to Modify

File	Change
`packages/coding-agent/docs/models.md`	Add "OpenAI Regional Endpoints" section with correct example
`packages/ai/src/providers/openai-responses.ts`	Check `OPENAI_BASE_URL` env var in `createClient()`
`packages/ai/src/providers/openai-completions.ts`	Check `OPENAI_BASE_URL` env var in `createClient()`
`packages/coding-agent/src/cli/args.ts`	Document `OPENAI_BASE_URL` in env vars section
`packages/ai/README.md`	Document `OPENAI_BASE_URL` environment variable

Implementation Details

For openai-responses.ts and openai-completions.ts, modify createClient():

Actually, the logic should be: env var overrides model.baseUrl when provider is "openai":

For docs/models.md, add under "Overriding Built-in Providers":

markdown

### OpenAI Regional Endpoints
For OpenAI projects with data residency requirements (US, EU), override the base URL.Note: The `/v1` path suffix is required.
```json{  "providers": {    "openai": {      "baseUrl": "https://us.api.openai.com/v1"    }  }}

Or set the environment variable: OPENAI_BASE_URL=https://us.api.openai.com/v1

just update docs, then comment on the issue telling the user what they did wrong and how to fix it

Readmodels.md

Editedmodels.md

Now let me comment on the issue:

>gh issue comment 956 --repo badlogic/pi-mono --body 'The issue is the missing `/v1` path suffix in your `baseUrl`. OpenAI models use `https://api.openai.com/v1` by default, so your override needs to include it too:

```json
{
  "providers": {
    "openai": {
      "baseUrl": "https://us.api.openai.com/v1"
    }
  }
}
```

Without `/v1`, the SDK hits an HTML error page instead of the API, which explains the garbage output you saw.

Updated the docs to make this clearer: https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/docs/models.md#openai-regional-endpoints'

Done. I've:

Updated docs/models.md: Added "OpenAI Regional Endpoints" subsection under "Overriding Built-in Providers" with the correct URL format (https://us.api.openai.com/v1)
Commented on issue #956: Explained that the missing /v1 suffix caused the SDK to hit an HTML page instead of the API, with the correct configuration example