Repository navigation
refactor(agent-server): map domain errors to HTTP once - #6780
Conversation
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).
REST API breakage checks (OpenAPI) — ✅ PASSEDResult: ✅ PASSED |
Coverage Report •
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
smolpaws
left a comment
There was a problem hiding this comment.
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.
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.
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.
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 astore_errors()context manager that turned store exceptions into statuses, and three domain exceptions with handlers of their own inapi.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 outsidestore_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_STATUSinopenhands/agent_server/errors.pymaps each category to a status, and it is the only place a status is chosen.Summary
openhands.sdk.errors:DomainErrorand 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_STATUSgives each one its status:Invalid(also aValueError)Unauthenticated/ForbiddenNotFound/Conflict/GoneMisdirectedUnprocessable(Invalid)RateLimitedOperationFailed/NotSupportedUpstreamFailed/UpstreamTimeout(UpstreamFailed)Busy,LockTimeout(Busy, TimeoutError),Unavailableapi.pyregisters oneDomainErrorhandler, which replaces the three dedicated handlers, and renders through the same code asHTTPException, so bodies, headers (Retry-After) and logging are unchanged.error_responses({NotFound: "..."})buildsresponses=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;ForwardedStatusrelays 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 througherror_for_status/ForwardedStatus, and the archived-runtime 410 becameGone;store_errors()andmeta_profiles_router._store_errors()are deleted, with their 35withblocks. The SDK stores (LLMProfileStore,AgentProfileStore,MetaProfileStore,ProviderConnectionStore,profile_refs) now raiseInvalidwhere they raisedValueError,LockTimeout(with the old "store is busy" detail) where they raisedTimeoutError, and wrap their unguarded JSON/model decoding inInvalid;ProviderConnectionNotFoundis anUnprocessable.ConversationRunLimitExceeded,ConversationOwnershipLostErrorandCredentialBindingActivationRequiredare categories now and keep theirRuntimeErrorbase and their exact bodies.Guard:
tests/cross/test_no_http_exception_outside_api.pyfails on anyHTTPExceptionin the agent server outsideapi.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.pyraises every category through the real_add_exception_handlersand asserts the response (status, JSON body,Retry-After) is identical to the one theHTTPExceptionwith the same status and detail produced, for text and structured details, a missing detail, anExceptionGroup, 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: mappingNotFoundto 400 fails 27 tests (this file andtest_conversation_router.py); dropping the extra body fields fails the credential-binding case..github/scripts/export_agent_server_openapi.py) is byte-identical tomainat 9f7d5cb: the generatedresponses=reproduce every status and description.FastAPI()call the newadd_domain_error_handler(app)(they relied on FastAPI's defaultHTTPExceptionhandler); direct calls expectDomainErrorand read the status withstatus_for; mocks that raised a bareTimeoutError/ValueErrorto stand in for a store raise the store'sLockTimeout/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:
Every failure is one that fails on
mainon this machine or only under parallel load:tests/agent_server: the 4test_canvas_extension_backend.pyfailures fail identically onmain(the backend manager reports no supported platform off Linux).tests/sdk:test_plugin_fetch_integration.py(3),test_truncate.py(1) andtest_mcp_client_subprocess_cleanup.py(2 here, 3 onmain) fail onmaintoo.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 underopenhands-tools,openhands-workspaceor the terminal code. I did not get a clean low-load terminal run to quote (39 still failed at-n 2while 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) andcheck_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
Notes
Status changes, all on paths that answered 500 before:
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.active_meta_profileanswers a busy meta-profile store with the meta-profile store's own wording (503: Meta-profile store is busy. Please retry.in the 5xxexceptionfield) instead of the generic profile-store wording.Narrowing to be aware of:
store_errors()turned everyValueErrorinside its blocks into a 400. The stores now raiseInvalidat everyValueErrorsource I found (explicit raises, JSON decoding, model validation); aValueErrorfrom 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 echoedstr(exc).Third-party store implementations (for example an enterprise
OrgLLMProfileLoader) that raise a bareValueError/TimeoutErrorused to get 400/503 throughstore_errors(); they should raiseInvalid/LockTimeoutto keep that.add_domain_error_handler(app)is public for apps that mount agent-server routers on their ownFastAPI(). Without it those apps answer domain errors with 500. Enterprise imports only_probe_mcp_serverand models frommcp_router, and that function raises none of them.DEBUG-only: the
tracebackfield of a deliberate 5xx now ends with the domain error (OperationFailed: Failed to read workspaces) rather thanHTTPException: 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
eclipse-temurin:17-jdkpython-node-runtimepython-node-runtimepython-node-runtimegolang:1.21-bookwormPull (multi-arch manifest)
# Each variant is a multi-arch manifest supporting both amd64 and arm64 docker pull ghcr.io/openhands/agent-server:f844af9-pythonRun
All tags pushed for this build
About Multi-Architecture Support
f844af9-python) is a multi-arch manifest supporting both amd64 and arm64f844af9-python-amd64) are also available if needed