Skip to content

V2: critical startup failures should show actionable errors #35158

Open

Description

@opencode-agent

Summary

V2 critical startup failures can show only a generic Failed to start server error plus bundled stack frames, without the real cause or an actionable next step.

Evidence

Reported from the V2 TODO LIST thread by James:
https://discord.com/channels/1391832426048651334/1520962938733723720/1522585807997894756

Screenshot showed:

ERROR (#1): Error: Failed to start server
  at ~effect/Utils/internal (/$bunfs/root/chunk-...js:...)
  at ...
  at service.start (...)

The visible output does not show why the server failed to start.

Expected behavior

Critical startup failures should surface a concise user-facing cause and likely fix. Examples:

  • port/socket already in use
  • invalid config
  • database open or migration failure
  • permission/path failure
  • daemon/server startup failure

Debug stack traces can remain available in verbose/debug mode, but the default failure should not be only /$bunfs/root/... stack frames.

Actual behavior

The CLI reports Failed to start server with bundled stack frames, but no actionable root cause.

Suggested scope

  • Preserve/unwrap the underlying startup failure cause when server startup fails.
  • Render a short actionable message before any stack trace.
  • Avoid showing only bundled /$bunfs/root/... stack frames by default.
  • Add smoke coverage for at least one startup failure path if feasible.

Related

Activity

  1. added
    bugSomething isn't working
    coreAnything pertaining to core functionality of the application (opencode server stuff)
    on Jul 3, 2026
  2. self-assigned this
    on Jul 12, 2026
  3. sghng commented on Sep 14, 2026

    @sghng

    Cross-linking #41696 as a concrete, still-open instance of this umbrella: the managed-service startup path hides a specific, actionable error (port already in use, with the service set port remediation hint) behind the generic Timed out waiting for the background service to start. Reproduced on release channel v2.0.3. The contender-overlap gap that swallows the error is pinpointed in code there (packages/client/src/effect/service.ts:122/138, also promise/service.ts:59), along with a suggested fix — retain the last contender failure and attach it as cause to the final timeout error. #41793 fixed the nonzero-exit path but not this timeout path.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

2.0bugSomething isn't workingcoreAnything pertaining to core functionality of the application (opencode server stuff)

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions