Skip to content

refactor(agent-server): map domain errors to HTTP once - #6780

Merged
VascoSch92 merged 1 commit into
mainfrom
vasco/domain-exceptions
Nov 12, 2026
Merged

VascoSch92 merged 1 commit into
mainfrom
vasco/domain-exceptions

Conversation

@VascoSch92

@VascoSch92 VascoSch92 commented Nov 12, 2026 •

Copy link
Copy Markdown
Member

HUMAN:

Refactoring how HTTP errors in the agent-server are handled


AGENT:

Why

The agent server mapped errors to HTTP at every call site: 328 hand-built HTTPExceptions across the routers and services, two copies of a store_errors() context manager that turned store exceptions into statuses, and three domain exceptions with handlers of their own in api.py. Anything a route forgot became a 500. #6456 lists the bugs this produced (#5906 a route copied without its error mapping, #5898 a route outside store_errors() in a file that already used it, #4991/#5795).

This PR replaces that with one table. Stores and services raise a small set of domain error categories; ERROR_STATUS in openhands/agent_server/errors.py maps each category to a status, and it is the only place a status is chosen.

Summary

  • openhands.sdk.errors: DomainError and its categories. The module has no HTTP in it and imports nothing from the SDK, so stores and services can raise from it. openhands.agent_server.errors.ERROR_STATUS gives each one its status:

    Category Status
    Invalid (also a ValueError) 400
    Unauthenticated / Forbidden 401 / 403
    NotFound / Conflict / Gone 404 / 409 / 410
    Misdirected 421
    Unprocessable(Invalid) 422
    RateLimited 429
    OperationFailed / NotSupported 500 / 501
    UpstreamFailed / UpstreamTimeout(UpstreamFailed) 502 / 504
    Busy, LockTimeout(Busy, TimeoutError), Unavailable 503
  • api.py registers one DomainError handler, which replaces the three dedicated handlers, and renders through the same code as HTTPException, so bodies, headers (Retry-After) and logging are unchanged. error_responses({NotFound: "..."}) builds responses= from the same table (60 routes); error_for_status() turns a status carried by a lower-level error (git provider, plugin fetch, launch) into its category; ForwardedStatus relays a status another server chose (the OpenAI gateway relaying a conversation runtime's reply).

  • All 328 HTTPException(...) constructions in the agent server are gone: 321 literal-status ones became categories by codemod (then reviewed), the 6 with a computed status go through error_for_status/ForwardedStatus, and the archived-runtime 410 became Gone; store_errors() and meta_profiles_router._store_errors() are deleted, with their 35 with blocks. The SDK stores (LLMProfileStore, AgentProfileStore, MetaProfileStore, ProviderConnectionStore, profile_refs) now raise Invalid where they raised ValueError, LockTimeout (with the old "store is busy" detail) where they raised TimeoutError, and wrap their unguarded JSON/model decoding in Invalid; ProviderConnectionNotFound is an Unprocessable. ConversationRunLimitExceeded, ConversationOwnershipLostError and CredentialBindingActivationRequired are categories now and keep their RuntimeError base and their exact bodies.

  • Guard: tests/cross/test_no_http_exception_outside_api.py fails on any HTTPException in the agent server outside api.py, which still handles FastAPI's own (routing, security) and renders domain errors through it. After this PR that is the only file; no allow-list entries.

Issue Number

Part of #6456 (step 3, domain exceptions part).

How to Test

Contract preservation:

  • tests/agent_server/test_domain_errors.py raises every category through the real _add_exception_handlers and asserts the response (status, JSON body, Retry-After) is identical to the one the HTTPException with the same status and detail produced, for text and structured details, a missing detail, an ExceptionGroup, and a forwarded status. It also pins the bodies of the three former special cases and the 503 detail each store's lock timeout now carries (with a real held file lock). Mutation checks: mapping NotFound to 400 fails 27 tests (this file and test_conversation_router.py); dropping the extra body fields fails the credential-binding case.
  • The exported public OpenAPI (.github/scripts/export_agent_server_openapi.py) is byte-identical to main at 9f7d5cb: the generated responses= reproduce every status and description.
  • Existing route tests keep their status assertions. Test changes are mechanical: apps built from bare FastAPI() call the new add_domain_error_handler(app) (they relied on FastAPI's default HTTPException handler); direct calls expect DomainError and read the status with status_for; mocks that raised a bare TimeoutError/ValueError to stand in for a store raise the store's LockTimeout/Invalid; one mini-app test that asserted FastAPI's default 5xx body now asserts the agent server's real 5xx body.

Runs on macOS, each suite in its own process:

uv run pytest tests/agent_server -n 6   # 3145 passed, 4 failed
uv run pytest tests/sdk tests/tools -n 8   # 9306 passed, 82 failed (see below)
uv run pytest tests/cross -n 4   # 729 passed
uv run pre-commit run --from-ref origin/main --to-ref HEAD   # all hooks pass

Every failure is one that fails on main on this machine or only under parallel load:

  • tests/agent_server: the 4 test_canvas_extension_backend.py failures fail identically on main (the backend manager reports no supported platform off Linux).
  • tests/sdk: test_plugin_fetch_integration.py (3), test_truncate.py (1) and test_mcp_client_subprocess_cleanup.py (2 here, 3 on main) fail on main too.
  • tests/tools: test_browser_executor_e2e.py (4) passes alone on this branch (28 passed); test_working_dir_standardization.py (1) passes alone; the terminal tests (tests/tools/terminal, 71 under -n 8) are the suite that fails under load on this Mac. This diff touches nothing under openhands-tools, openhands-workspace or the terminal code. I did not get a clean low-load terminal run to quote (39 still failed at -n 2 while another suite ran beside it); CI is the check for that suite.

check_sdk_api_breakage.py (no breaking changes in openhands-sdk/workspace/tools against 1.62.0) and check_persisted_settings_compat.py (33 fixtures, 8 PyPI payloads) pass locally.

Video/Screenshots

N/A (no UI). The OpenAPI and response-parity evidence is above.

Type

  • Bug fix
  • Feature
  • Refactor
  • Breaking change
  • Docs / chore

Notes

Status changes, all on paths that answered 500 before:

  • A store error raised outside the old store_errors() blocks is now mapped where it used to be unhandled: a lock timeout answers 503, an invalid name or unreadable store file 400, a dangling provider connection 422.
  • The settings route that checks active_meta_profile answers a busy meta-profile store with the meta-profile store's own wording (503: Meta-profile store is busy. Please retry. in the 5xx exception field) instead of the generic profile-store wording.

Narrowing to be aware of: store_errors() turned every ValueError inside its blocks into a 400. The stores now raise Invalid at every ValueError source I found (explicit raises, JSON decoding, model validation); a ValueError from somewhere else inside those routes (for example a pydantic serialization error while saving with a misconfigured cipher context, or _seed_default_profile) becomes a logged 500 instead of a 400 that echoed str(exc).

Third-party store implementations (for example an enterprise OrgLLMProfileLoader) that raise a bare ValueError/TimeoutError used to get 400/503 through store_errors(); they should raise Invalid/LockTimeout to keep that.

add_domain_error_handler(app) is public for apps that mount agent-server routers on their own FastAPI(). Without it those apps answer domain errors with 500. Enterprise imports only _probe_mcp_server and models from mcp_router, and that function raises none of them.

DEBUG-only: the traceback field of a deliberate 5xx now ends with the domain error (OperationFailed: Failed to read workspaces) rather than HTTPException: 500: ...; the verify-agent-server skill references are updated.

Conflicts to expect: #6702 (ServerContext) and #6612 (cipher binding) touch the same routers and persistence/store.py; the sibling step-3 PRs (SecretField, async store facade) touch the stores.


🐳 Agent Server images for this PR — GHCR package, pull/run commands, and all pushed tags (click to expand)

• GHCR package: https://github.com/OpenHands/agent-sdk/pkgs/container/agent-server

Variants & Base Images

Variant Architectures Base Image Docs / Tags
java amd64, arm64 eclipse-temurin:17-jdk Link
python-slim amd64, arm64 python-node-runtime Link
python-minimal amd64, arm64 python-node-runtime Link
python amd64, arm64 python-node-runtime Link
golang amd64, arm64 golang:1.21-bookworm Link

Pull (multi-arch manifest)

# Each variant is a multi-arch manifest supporting both amd64 and arm64
docker pull ghcr.io/openhands/agent-server:f844af9-python

Run

docker run -it --rm \
  -p 8000:8000 \
  --name agent-server-f844af9-python \
  ghcr.io/openhands/agent-server:f844af9-python

All tags pushed for this build

ghcr.io/openhands/agent-server:f844af9-golang-amd64
ghcr.io/openhands/agent-server:f844af9d0b7a8723118708c5a6c692bde5727308-golang-amd64
ghcr.io/openhands/agent-server:vasco-domain-exceptions-golang-amd64
ghcr.io/openhands/agent-server:f844af9-golang_tag_1.21-bookworm-amd64
ghcr.io/openhands/agent-server:f844af9-golang-arm64
ghcr.io/openhands/agent-server:f844af9d0b7a8723118708c5a6c692bde5727308-golang-arm64
ghcr.io/openhands/agent-server:vasco-domain-exceptions-golang-arm64
ghcr.io/openhands/agent-server:f844af9-golang_tag_1.21-bookworm-arm64
ghcr.io/openhands/agent-server:f844af9-java-amd64
ghcr.io/openhands/agent-server:f844af9d0b7a8723118708c5a6c692bde5727308-java-amd64
ghcr.io/openhands/agent-server:vasco-domain-exceptions-java-amd64
ghcr.io/openhands/agent-server:f844af9-eclipse-temurin_tag_17-jdk-amd64
ghcr.io/openhands/agent-server:f844af9-java-arm64
ghcr.io/openhands/agent-server:f844af9d0b7a8723118708c5a6c692bde5727308-java-arm64
ghcr.io/openhands/agent-server:vasco-domain-exceptions-java-arm64
ghcr.io/openhands/agent-server:f844af9-eclipse-temurin_tag_17-jdk-arm64
ghcr.io/openhands/agent-server:f844af9-python-amd64
ghcr.io/openhands/agent-server:f844af9d0b7a8723118708c5a6c692bde5727308-python-amd64
ghcr.io/openhands/agent-server:vasco-domain-exceptions-python-amd64
ghcr.io/openhands/agent-server:f844af9-python-node-runtime-amd64
ghcr.io/openhands/agent-server:f844af9-python-arm64
ghcr.io/openhands/agent-server:f844af9d0b7a8723118708c5a6c692bde5727308-python-arm64
ghcr.io/openhands/agent-server:vasco-domain-exceptions-python-arm64
ghcr.io/openhands/agent-server:f844af9-python-node-runtime-arm64
ghcr.io/openhands/agent-server:f844af9-python-minimal-amd64
ghcr.io/openhands/agent-server:f844af9d0b7a8723118708c5a6c692bde5727308-python-minimal-amd64
ghcr.io/openhands/agent-server:vasco-domain-exceptions-python-minimal-amd64
ghcr.io/openhands/agent-server:f844af9-python-node-runtime-minimal-amd64
ghcr.io/openhands/agent-server:f844af9-python-minimal-arm64
ghcr.io/openhands/agent-server:f844af9d0b7a8723118708c5a6c692bde5727308-python-minimal-arm64
ghcr.io/openhands/agent-server:vasco-domain-exceptions-python-minimal-arm64
ghcr.io/openhands/agent-server:f844af9-python-node-runtime-minimal-arm64
ghcr.io/openhands/agent-server:f844af9-python-slim-amd64
ghcr.io/openhands/agent-server:f844af9d0b7a8723118708c5a6c692bde5727308-python-slim-amd64
ghcr.io/openhands/agent-server:vasco-domain-exceptions-python-slim-amd64
ghcr.io/openhands/agent-server:f844af9-python-node-runtime-slim-amd64
ghcr.io/openhands/agent-server:f844af9-python-slim-arm64
ghcr.io/openhands/agent-server:f844af9d0b7a8723118708c5a6c692bde5727308-python-slim-arm64
ghcr.io/openhands/agent-server:vasco-domain-exceptions-python-slim-arm64
ghcr.io/openhands/agent-server:f844af9-python-node-runtime-slim-arm64
ghcr.io/openhands/agent-server:f844af9-golang
ghcr.io/openhands/agent-server:f844af9d0b7a8723118708c5a6c692bde5727308-golang
ghcr.io/openhands/agent-server:vasco-domain-exceptions-golang
ghcr.io/openhands/agent-server:f844af9-golang_tag_1.21-bookworm
ghcr.io/openhands/agent-server:f844af9-java
ghcr.io/openhands/agent-server:f844af9d0b7a8723118708c5a6c692bde5727308-java
ghcr.io/openhands/agent-server:vasco-domain-exceptions-java
ghcr.io/openhands/agent-server:f844af9-eclipse-temurin_tag_17-jdk
ghcr.io/openhands/agent-server:f844af9-python-minimal
ghcr.io/openhands/agent-server:f844af9d0b7a8723118708c5a6c692bde5727308-python-minimal
ghcr.io/openhands/agent-server:vasco-domain-exceptions-python-minimal
ghcr.io/openhands/agent-server:f844af9-python-node-runtime-minimal
ghcr.io/openhands/agent-server:f844af9-python-slim
ghcr.io/openhands/agent-server:f844af9d0b7a8723118708c5a6c692bde5727308-python-slim
ghcr.io/openhands/agent-server:vasco-domain-exceptions-python-slim
ghcr.io/openhands/agent-server:f844af9-python-node-runtime-slim
ghcr.io/openhands/agent-server:f844af9-python
ghcr.io/openhands/agent-server:f844af9d0b7a8723118708c5a6c692bde5727308-python
ghcr.io/openhands/agent-server:vasco-domain-exceptions-python
ghcr.io/openhands/agent-server:f844af9-python-node-runtime

About Multi-Architecture Support

  • Each variant tag (e.g., f844af9-python) is a multi-arch manifest supporting both amd64 and arm64
  • Docker automatically pulls the correct architecture for your platform
  • Individual architecture tags (e.g., f844af9-python-amd64) are also available if needed

Stores and services raise categories from the new openhands.sdk.errors
(NotFound, Conflict, Invalid, Unprocessable, Busy, LockTimeout,
Unavailable, RateLimited, ...). openhands.agent_server.errors.ERROR_STATUS
is the only place a category gets a status; api.py registers one handler
for it, and routes build responses= from the same table.

The 328 hand-built HTTPExceptions in the agent server, the two
store_errors() context managers and the three dedicated handlers in
api.py are gone. The profile, meta-profile and provider-connection stores
raise Invalid / LockTimeout themselves (still ValueError / TimeoutError),
so the routes no longer translate their exceptions. Status codes, bodies
and the exported OpenAPI are unchanged; paths that answered 500 because a
store error escaped the old blocks now get the mapped status.

A guard test fails on any HTTPException in the agent server outside
api.py.

Part of #6456 (step 3, domain exceptions part).
@github-actions

Copy link
Copy Markdown
Contributor

REST API breakage checks (OpenAPI) — ✅ PASSED

Result: ✅ PASSED

Action log

@github-actions

Copy link
Copy Markdown
Contributor

Coverage

Coverage Report •
FileStmtsMissCoverMissing
openhands-agent-server/openhands/agent_server
   _secrets_exposure.py67396%32, 83, 121
   acp_router.py96496%109–111, 140
   agent_profiles_router.py2331394%102, 188, 192, 196, 215, 218, 313, 316, 319–320, 499, 535–536
   api.py4543493%144, 198–199, 208–209, 211, 214–215, 222–223, 237–238, 255, 261, 264–265, 359, 373, 379, 442, 447, 460–462, 495, 524, 530, 534, 555–556, 842, 845, 847, 853
   auth_router.py46198%79
   bash_router.py72790%83–86, 96–97, 145
   canvas_extensions_router.py184796%217, 349, 357–360, 362
   conversation_lease.py1471193%44–45, 58, 65, 248, 254, 256, 258, 272–273, 277
   conversation_router.py3251795%118–119, 122–123, 252, 343, 477, 526, 584, 757, 819–821, 865, 902–903, 934
   conversation_service.py128510092%194–195, 277, 298, 487–488, 654, 661–662, 763, 854, 905–906, 913, 945–946, 962, 993, 997, 1009, 1029, 1050–1051, 1060, 1129, 1139, 1164, 1170–1171, 1175–1176, 1184, 1211, 1217, 1311, 1317, 1322, 1328, 1336–1337, 1346–1349, 1358, 1371, 1389, 1426, 1430–1434, 1457, 1506, 1519, 1527, 1585–1586, 1590, 1804, 1882, 2006, 2009, 2016–2018, 2021–2022, 2028, 2038, 2042, 2071, 2080, 2139–2141, 2172, 2303, 2306, 2333, 2343, 2348–2351, 2365, 2376, 2388–2389, 2421, 2519, 2579, 2637, 2652–2653, 3059, 3112, 3115, 3128
   credential_binding.py82989%48, 63–64, 67–68, 87–88, 132, 145
   dependencies.py56395%60, 93, 103
   errors.py26196%84
   event_router.py137795%318, 328, 331–332, 383–384, 424
   event_service.py112411090%166, 172–173, 306–307, 437, 441, 446, 473, 480, 515, 518–519, 523–524, 535, 541, 612–613, 619, 675–676, 797, 817, 844, 853, 877–878, 882, 930, 965, 969–970, 1005, 1012, 1018, 1232, 1262, 1265, 1343, 1361, 1375, 1544–1545, 1600, 1634, 1790–1793, 1797, 1840, 1844, 1851, 1865, 1879, 1903, 1950–1952, 2036, 2058, 2061–2062, 2087, 2093, 2095, 2111, 2113, 2120, 2128, 2130–2131, 2135, 2152, 2204, 2210, 2219–2220, 2227, 2242, 2253, 2294–2297, 2377–2378, 2380–2387, 2389–2390, 2400, 2411, 2427–2428, 2439, 2466, 2472, 2478, 2487–2488, 2510, 2520
   file_router.py4877485%130–132, 158–160, 228–230, 343, 346–347, 354–355, 393, 395–397, 446, 490–493, 499–501, 507–509, 521–522, 559, 627–629, 634, 638–640, 682–683, 692, 699, 720–722, 770–772, 796–797, 801–802, 810, 812–817, 820–822, 897–898, 902–903, 1108–1114
   git_router.py1221191%123–125, 136–138, 165, 207, 267, 279, 282
   init_router.py178597%214, 216, 220, 222, 224
   launch.py124497%165, 168–169, 194
   llm_router.py146795%101, 107, 129, 249–251, 274
   mcp_router.py3953791%197, 200, 206, 211, 393, 428–430, 433–434, 437, 468–471, 474–475, 479–480, 524–525, 657–659, 889, 920–921, 928, 956, 961, 969, 993, 995–996, 1006–1008
   meta_profiles_router.py110199%173
   plugins_router.py141299%349–350
   profiles_router.py212697%527–532
   provider_connections_router.py127993%193–194, 209, 215, 236–237, 255, 261–262
   runtime_router.py53492%40, 56–57, 59
   settings_router.py213598%586, 588–589, 628, 633
   workspace_router.py48198%55
   workspaces_router.py1272382%70–72, 116–117, 146–151, 190–195, 221–226
openhands-agent-server/openhands/agent_server/canvas_extensions
   bridge.py2902691%124, 140, 155, 171–173, 238–239, 246, 249, 256, 265, 268, 271, 314, 319, 340, 353, 356, 379, 394, 448, 499–501, 506
openhands-agent-server/openhands/agent_server/docker_runtime
   proxy.py1351291%88–89, 129, 234, 256, 259, 276, 280, 286, 290, 307–308
   routers.py2777075%73, 81, 88–90, 133–135, 150–151, 153, 182, 190–191, 236, 259, 262–265, 268–272, 305–306, 339, 348, 358, 364–366, 376–378, 387, 390, 400–401, 441, 455–456, 499–501, 522, 524–537, 540–542, 548–551, 562, 571
openhands-agent-server/openhands/agent_server/openai
   router.py75396%77, 110, 116
   service.py3375584%108, 116–119, 127, 131–141, 143–147, 162, 188–193, 224, 233, 235, 257, 267–268, 364, 371, 378, 397–400, 497–498, 581–582, 588, 595–596, 670–671, 695, 711, 719, 782
openhands-sdk/openhands/sdk/llm
   llm_profile_store.py1851095%63–64, 76–77, 79, 182–183, 383, 415, 421
   meta_profile_store.py104793%141, 144, 239–241, 272–273
   provider_connection_store.py1501590%112, 119, 139, 174, 177, 199, 202, 204, 233–235, 254, 258, 260, 277
openhands-sdk/openhands/sdk/profiles
   agent_profile_store.py1761194%91–92, 275–276, 282, 302, 308, 310, 425–426, 451
TOTAL55519872484% 

@VascoSch92
VascoSch92 marked this pull request as ready for review November 12, 2026 10:26

@smolpaws smolpaws left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi, I’m Codex (posting as @smolpaws), reviewing this PR at Engel’s request.

Reviewed f844af9d0, including the domain hierarchy and HTTP mapping, all migrated production call sites, removed store-error wrappers, exception inheritance/catch interactions, and response bodies/headers. I found no material correctness or compatibility regression.

Independent validation: 390 tests passed across domain errors, the HTTPException guard, profiles, meta-profiles, agent profiles, and settings routes. An independent second pass also checked the error boundaries and secret exposure. Current-head CI is green, including server/SDK/cross tests, persistence and REST compatibility, pre-commit, and packaged builds.

Approved.

@VascoSch92
VascoSch92 merged commit 10be259 into main Nov 12, 2026
53 of 54 checks passed
@VascoSch92
VascoSch92 deleted the vasco/domain-exceptions branch November 12, 2026 14:34
@enyst enyst mentioned this pull request Nov 12, 2026
1 of 5 tasks
VascoSch92 added a commit that referenced this pull request Nov 12, 2026
Fifty files conflicted, most of them with #6780 (domain errors), which
rewrote the raises in every router this branch rewrote the lookups of.
Each conflict keeps main's errors, responses and new behaviour and this
branch's injected dependencies.

Code main added since the branch point that used lookups this branch
removed now takes its dependencies like the rest:

- experimental features (#6759): the routes take the settings store
  through Depends(get_settings_store).
- conversation reactions (#6609): require_reactions_enabled takes a
  settings store; the route injects it and the Docker proxy passes the
  registry's.
- pull request status (#6704): get_provider_pull_request takes the
  secrets store.
- trajectory download (#5766): uses the injected config.
- DockerConversationRegistry and the OpenAI gateway read experimental
  features from their own ServerStores.

Code that exists only on this branch raises domain errors too
(dependencies.py, init_router.py, vscode_router.py); a WebSocket that
finds no service still closes with 1013.

Tests main added for these features build their stores per test instead
of reading a process-wide one.
@enyst enyst mentioned this pull request Nov 14, 2026
1 of 5 tasks
vnktadithya added a commit to vnktadithya/OpenHands-software-agent-sdk that referenced this pull request Nov 15, 2026
Adapts the branch to two upstream changes in the same area:

- OpenHands#6780 maps domain errors to HTTP in one place. The metadata lock timeout
  is now a LockTimeout, so ERROR_STATUS answers 503; the branch's own
  exception handler in api.py is gone, and routes declare the 503 with
  error_responses(). Canvas install re-raises LockTimeout before its
  OSError clause, since a LockTimeout is also an OSError.
- OpenHands#5756 adds strict loading. strict stays on list_installed, load_installed,
  sync and load_from_dir. InstallationMetadata.open() drops it: a session
  already refuses metadata it cannot load, so strict had no effect there.

OpenHands#6702 removed reset_stores(); the responsiveness test no longer needs it,
as create_app() builds its own stores.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants