---
title: "OpenCode serve 401 Loop and Endless Basic Auth Prompts: How to Debug It"
description: "Why opencode serve gets stuck in a browser Basic Auth loop or 401 spinner—how to isolate empty env vars, test the default opencode username with curl, check refresh requests, and fix proxy double-auth."
url: https://codingpass.ai/blog/opencode-serve-basic-auth-401-loop
language: en
updated: 2026-11-20
---
# OpenCode serve 401 Loop: Why the Login Popup Won’t Stop

You run opencode serve and open the Web UI, only to hit an endless HTTP Basic Auth dialog or an infinite loading spinner returning 401. Stepping through env vars, curl, DevTools, and your reverse proxy isolates the exact cause.

[CodingPass team](https://codingpass.ai/about) Published Nov 20, 2026 Updated Nov 20, 2026 5 min read

When you start `opencode serve` or `opencode web` in OpenCode 2.x and open it in a browser, it is surprisingly easy to get stuck in one of two loops: either you never set a password yet the Web UI spins forever on `401 Unauthorized`, or you did set a password, typed it in, and the browser still pops up the HTTP Basic Auth dialog every few seconds.

Re-entering credentials in the browser rarely tells you what is wrong. Stepping out of the browser and checking the environment, `curl`, the Network tab, and any reverse proxy in front of OpenCode narrows it down in minutes.

Two details trip people up right away: setting `OPENCODE_SERVER_PASSWORD=""` is not the same as unsetting it, and whenever server auth is active, OpenCode expects the default username `opencode`.

## Step 1: Check for an empty `OPENCODE_SERVER_PASSWORD`

When `OPENCODE_SERVER_PASSWORD` is completely unset, `opencode serve` is meant to run without authentication. However, leaving `OPENCODE_SERVER_PASSWORD=""` in `.env` or a shell profile—or hitting the unset-password regression tracked in [anomalyco/opencode#50370](https://github.com/anomalyco/opencode/issues/50370)—makes endpoints return `401 Unauthorized` without a working auth prompt, leaving the Web UI stuck on an infinite loading spinner.

If you are running locally or on a trusted network without auth, clear both variables rather than leaving them blank:

```
unset OPENCODE_SERVER_PASSWORD
unset OPENCODE_SERVER_USERNAME
opencode serve
```

## Step 2: Test with `curl` before blaming the browser

If you want password protection enabled, the easiest detail to miss in the browser dialog is the **username**. When `OPENCODE_SERVER_PASSWORD` is set, OpenCode defaults `OPENCODE_SERVER_USERNAME` to **`opencode`**—not your macOS/Linux username, and not empty.

Export both explicitly before starting the server:

```
export OPENCODE_SERVER_USERNAME="opencode"
export OPENCODE_SERVER_PASSWORD="your-password"
opencode serve
```

Then hit `/global/health` directly from a second terminal to bypass browser caches and password managers:

```
curl -i -u opencode:your-password http://127.0.0.1:4096/global/health
```

- If `curl` returns `200`, your credentials and server are fine; the loop is coming from the browser or a proxy.
- If `curl` also returns `401` on `v2 serve`, your installed build is likely affected by the auth validation regression in [#45856](https://github.com/anomalyco/opencode/issues/45856); upgrade OpenCode and retest.

## Step 3: Check DevTools Network for refresh re-prompts

Sometimes the first login succeeds, only for the Basic Auth dialog to come right back when you reload the page. In DevTools Network, secondary requests such as `/site.webmanifest` or `/global/health` can return `401` and re-trigger the browser prompt ([#18325](https://github.com/anomalyco/opencode/issues/18325)). Native Basic Auth dialogs also clash with browser password managers, which frequently autofill the wrong username and turn a single retry into a loop.

## Step 4: Check your reverse proxy and `opencode attach` flags

Another common trap is double authentication: if `opencode serve` sits behind Nginx, Caddy, or Cloudflare Access that already handles login, leaving `OPENCODE_SERVER_PASSWORD` enabled makes both layers emit conflicting `WWW-Authenticate` headers. Bind `opencode serve` to `127.0.0.1` with `OPENCODE_SERVER_PASSWORD` unset so only the proxy challenges the browser.

If the `401` happens in a second terminal (`opencode attach`) or an external SDK rather than a browser ([#31254](https://github.com/anomalyco/opencode/issues/31254)), pass `-p` explicitly (plus `-u` if you changed the username):

```
opencode attach http://localhost:4096 -p your-password
```

## Quick lookup by symptom

| Symptom | What to check first |
| --- | --- |
| Infinite loading / 401 with no password set | Make sure `OPENCODE_SERVER_PASSWORD=""` is not exported; run `unset` before starting |
| Browser keeps rejecting the right password | Use username `opencode` and verify with `curl -u opencode:...` |
| Looping behind Nginx / Caddy / Cloudflare Access | Unset `OPENCODE_SERVER_PASSWORD` on OpenCode so only the proxy handles auth |
| `opencode attach` or SDK gets 401 | Pass `-p <password>` or send Basic Auth headers explicitly |

One last distinction: `OPENCODE_SERVER_PASSWORD` only guards OpenCode's local HTTP server and has nothing to do with your model API key. For CodingPass, set your model key separately via `opencode service set env CODINGPASS_API_KEY cp-live-...` as covered in the [OpenCode setup guide](https://codingpass.ai/tools/opencode).

Written by CodingPass team

We run CodingPass and test each guide against the latest stable release of the tool before we publish it. Spotted something out of date? Write to [support@codingpass.ai](mailto:support@codingpass.ai).

## Related reading.

Guide

### [OpenCode setup guide](https://codingpass.ai/tools/opencode)

Provider config in opencode.jsonc, model IDs per plan, and how to check common errors.

Rules

### [How allowances and caps work](https://codingpass.ai/usage-limits)

Allowances and caps for every plan and model, plus the 429 response.

Models

### [All models](https://codingpass.ai/models)

Model IDs, required tiers, and monthly allowances.
