Repository navigation
fix(workflows): return structured 500 on service-layer exceptions - #17347
Conversation
Design Review (Opus 5.5, fork) — ✅ PASSDesign-level review of Design-Verdict: PASS Check that the frontend's error handling for these four endpoints reads the new [DESIGN-REVIEWED] f3daaaa Description read[DESCRIPTION-READ] b503918b82ffbb8eb62f629bd6287365648a2343be81e630c148a162a3695deb That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with |
First Principles Review (Opus 5.5, fork) — 🟡 CONCERNSPremise-level review of First-Principles-Verdict: CONCERNS Point patch: a per-handler try/except in four handlers, while Not justified as shipped
What this change shipsInventory (3 items) — 2 justifiedIntent: give callers a JSON error they can diagnose, instead of a bare 500, when a workflow run or author service call raises. FIX (#17337, plus a test that fails on base).
[FIRST-PRINCIPLES-REVIEWED] f3daaaa Description read[DESCRIPTION-READ] 8cc892de309aeb439236b4e1b225391f0df3b637e4f395ba45117a16774f01d4 That sha256 names the PR description this verdict read. Recompute it with |
GPT 6.1 Review (fork) — ✅ no blocking findingsReviewed Review detailsNo findings. |
Opus 5.5 Review (fork) — ✅ no blocking findingsReviewed |
The api_workflow_run, api_workflow_run_intent, api_workflow_run_rerun, and api_workflow_author handlers called their service methods with no try/except, so any exception escaped as an opaque aiohttp 500 with no JSON body. A caller could not tell a deterministic platform fault (e.g. the glibc < 2.28 "atomic no-replace rename is unavailable" NotImplementedError, before the syscall fallback in kirodotdev#11018) from a transient failure, and backed off as if the service were unhealthy. Wrap all four handlers in the same try/except pattern the sibling api_workflow_run_definition already uses: log via logger.exception and return a structured {"error", "code"} 500. Each handler gets its own stable code so the failure class is diagnosable. Fixes kirodotdev#17337
c869c99 to
f3daaaa
Compare
iamwhatever
left a comment
There was a problem hiding this comment.
Approving (crew-pr-reviewer). The service-layer calls for workflow author and run are wrapped. An exception is logged with its traceback and returns a structured JSON 500 with a stable code, instead of an opaque 500. The success paths are unchanged. The client sees a fixed message, not exception text. CI is green and the base is main.
Problem / Motivation
Goal: Make a deterministic failure in the workflow run/author endpoints return a diagnosable JSON error instead of an opaque HTTP 500.
On Amazon Linux 2 (glibc 2.26) a deterministic platform fault surfaced as an opaque aiohttp 500 from the workflow run endpoints. The
renameat2glibc wrapper symbol was absent (added in glibc 2.28), the workflow memory binding failed closed withNotImplementedError("atomic no-replace rename is unavailable"), and that exception propagated out of the handler with no JSON body — so the caller could not tell a deterministic fault from a transient one and backed off as if the service were unhealthy.The underlying
renameat2syscall fallback already shipped in #11018, so the primary fault no longer reproduces. But the error-handling gap remains and is platform-independent:api_workflow_run,api_workflow_run_intent,api_workflow_run_rerun, andapi_workflow_authorcall their service methods with notry/except, unlike the siblingapi_workflow_run_definition.Why it matters
Any future service-layer exception in these four handlers still becomes an undiagnosable 500 with no body. A structured
{"error", "code"}response lets a caller log and classify the failure instead of guessing whether the service is transiently unhealthy.Not a goal
renameat2syscall fallback (already on main via fix: preserve member identity through dispatch and continuation #11018).What changed (motivation → approach → change)
Observed symptom: a deterministic fault escaped
api_workflow_run_intentas a bodyless 500. Root cause: the four workflow mutation handlers call their service method with no exception boundary, unlikeapi_workflow_run_definitionwhich wraps its call. Change: wrapped the service call in all four handlers (api_workflow_run,api_workflow_run_intent,api_workflow_run_rerun,api_workflow_author) with the sametry/except Exception → logger.exception(...) → return _error(message, code, 500)pattern the sibling already uses. Each handler returns its own stable code (workflow_run_failed,workflow_run_intent_failed,workflow_rerun_failed,workflow_author_failed).Backwards compatibility
Compatible: no behaviour change on the success path or on the existing validation (400/403/404/409/503) paths. The only difference is that an exception that previously escaped as a bare 500 now returns a structured JSON 500 with the same status code.
Removes nothing: the change only adds an exception boundary; no field, path, record, kind, key, or function is removed, renamed, or tightened.
Tests
Added
test_mutation_handlers_return_structured_500_on_service_errortotest/test_workflow_handler_json_contract.py: parametrized over all four handlers, each service method is made to raise, and the test asserts a 500 with a JSON{"error", "code"}body carrying the handler's stable code. The existing success-path and reject-non-object tests continue to pass. Full file: 17 passed.Manual verification
PYTHONPATH=src pytest test/test_workflow_handler_json_contract.py -n 2→ 17 passed. N/A for UI — this change touches no frontend surface.Related Issues
Fixes #17337
Pattern harvest
Rule candidate: review-prompt
Pattern: an aiohttp handler calling a service method with no
try/exceptlets a deterministic fault escape as a bodyless 500 — a sibling handler in the same module already had the boundary, so this is a drift-from-established-pattern class, not a one-off.