Bootstrap blocks first POST /session for minutes: hung models.opencode.ai fetch has no timeout, and plugin dep-install also blocks bootstrap #47279

title: "Bootstrap blocks first POST /session for minutes: hung models.opencode.ai fetch has no timeout, and plugin dep-install also blocks bootstrap"

Environment

• opencode-ai 1.18.26 and 1.18.27 (both stall identically)
• opencode serve --hostname 0.0.0.0 --port 4096 (headless, used as PID 1 in a per-project sandbox container)
• Docker Desktop on macOS (Ubuntu 22.04 container, arm64); also observed on a GCP-hosted dev sandbox
• Workspace contains a local TypeScript plugin (.opencode/plugins/ask-user.ts)

Summary

Two independent bootstrap behaviors make the first POST /session after every fresh opencode serve boot block for minutes on networks where the relevant connections stall:

1. The models.dev catalog fetch has no effective timeout and blocks instance creation. opencode fetches https://models.opencode.ai/api.json at bootstrap. On our host the TCP connection establishes and then goes silent for 210s+ (zero payload bytes — pcap-verified, ~50s of only-handshake traffic then idle). During that wait, GET /global/health answers instantly but POST /session hangs — the instance never finishes creating. A plain curl to the same URL from the same container returns 200 in 0.29s, so the endpoint is fine; it's specifically opencode's bootstrap client (Bun fetch, ~50 parallel TLS connections) getting throttled/hung by the path.

2. The "background dependency install" for local plugins blocks bootstrap. For ANY .ts plugin file in the workspace (even one with zero imports), opencode runs an npm install of @opencode-ai/plugin against registry.npmjs.org for both /workspace/.opencode and ~/.config/opencode, and instance creation waits for it. When the registry connection stalls, this adds minutes. Log once it finally fails:

   WARN message="background dependency install failed" dir=/workspace/.opencode
        error="…NpmInstallFailedError (request to https://registry.npmjs.org/@opencode-ai%2fplugin failed…)"
   WARN (same for dir=/home/analyst/.config/opencode)
   

Reproduction

Fresh container, image with opencode-ai@1.18.26, workspace holding one minimal plugin file:

mkdir -p ws/.opencode/plugins
cat > ws/.opencode/plugins/ask-user.ts <<'EOF'
export const AskUser = async () => ({ tool: { ask_user: { description: "no-op", args: {}, async execute() { return "ok" } } } })
EOF
docker run -d --name oc-probe -p 127.0.0.1:4096:4096 -v "$PWD/ws":/workspace \
  opencode-ai:1.18.26 opencode serve --hostname 0.0.0.0 --port 4096 --log-level DEBUG --print-logs
# then time this — it blocks ~60–300s on a throttled network; ~2s with --pure (but --pure kills plugins):
time curl -s -X POST http://127.0.0.1:4096/session -H 'content-type: application/json' -d '{"title":"t"}'

Container log during the wait (identical shape every run):

… message=loading path=/workspace/.opencode/opencode.jsonc
── 60–300s silence (no log lines, no network packets, low CPU) ──
… level=WARN message="background dependency install failed" … / level=ERROR "Failed to fetch models.dev" …
… message=init
… message=created id=ses_…

Evidence

• /proc/net/tcp sampled every 3s during a stall: a single ESTABLISHED connection to 172.66.173.149:443 (models.opencode.ai) held for 210s+ with zero payload; blocking the host via --add-host models.opencode.ai:127.0.0.1 makes the fetch error in <1s (Failed to fetch models.dev … Unable to connect).
• With the fetch blocked, the residual wait is not network: during the remaining 60–90s window there are zero sockets, zero DNS queries, low CPU — an internal block in the plugin/dependency-install path. Pre-seeding /workspace/.opencode/node_modules/@opencode-ai/plugin does not eliminate the wait; the installer still runs and bootstrap still waits for it.
• --pure boots in ~2s (proving the wait is plugin-loading-path), but is debugging-only and disables all plugins.
• OPENCODE_STRICT_CONFIG_DEPS=false had no effect in our runs.
• The models.opencode.ai fetch also fails fast and async when blocked — yet bootstrap still doesn't proceed until much later, so the fetch and the dep-install appear to be two separate bootstrap-phase waits.

Expected

• A non-critical catalog fetch (models.dev) should never block instance creation — fetch async, fall back to the bundled catalog on failure, and enforce a short timeout (the fetch is already known-optional; cf. v2: config-declared custom-provider models silently become 0 in catalog when models.opencode.ai fetch fails at boot (provider survives, resolution-by-ID still works) #41360 where its failure silently zeroes the catalog).
• A local .ts plugin with no external imports should not trigger a network dependency install that blocks the first session; @opencode-ai/plugin types/SDK resolution should be satisfiable locally (e.g. from the opencode install itself), and the install should be async/best-effort rather than blocking bootstrap.

Workarounds we ship (InsightForge sandbox)

• docker run --add-host models.opencode.ai:127.0.0.1 … — kills the 3.5-min hang, loss-free for us (we never use the free catalog). Note: cannot bake into the image — /etc/hosts is read-only at build time.
• Pre-install @opencode-ai/plugin@<same version as opencode> and copy it into each workspace's .opencode/node_modules before boot (entrypoint script).
• Backend warm-up creates a throwaway session after every boot transition; even so, worst-case observed provisioning went 4m55s → 2m32s with both mitigations.

Result: provisioning that takes 295s → ~152s locally (still not acceptable), ~2s on clean networks. Happy to provide pcaps/extra logs if useful.

Related

• v2: config-declared custom-provider models silently become 0 in catalog when models.opencode.ai fetch fails at boot (provider survives, resolution-by-ID still works) #41360 — models.opencode.ai fetch failing at boot zeroes config-declared catalog models (same fetch, different symptom: we care about the blocking behavior)
• [WSL2] single opencode run deadlocks during bootstrap before provider dispatch (no plugins, no concurrent process, no zombie child) #46142 — WSL2 bootstrap deadlock before provider dispatch (possibly the same internal plugin-path wait)
• Desktop: background dependency install failed - @opencode-ai/plugin@local version not found #30197 / Electron sidecar: npm plugins fail to load — peer dep @opencode-ai/plugin resolves as @local #26085 / Desktop app hangs on Windows 11 - @opencode-ai/plugin@local npm install failed #31708 — "background dependency install failed" family