{"record":{"id":"553e574449f6f236","repo":"bytedance/deer-flow","slug":"str-exc-553e57","errorCode":null,"errorMessage":"str(exc)","messagePattern":"str\\(exc\\)","errorType":"http","errorClass":"HTTPException","httpStatus":422,"severity":"error","filePath":"backend/app/gateway/services.py","lineNumber":1069,"sourceCode":"    body: RunCreateRequest,\n    thread_id: str,\n    request: Request,\n) -> RunRecord:\n    \"\"\"Create a RunRecord and launch the background agent task.\n\n    Parameters\n    ----------\n    body : RunCreateRequest\n        The validated request body shared by HTTP and internal launch paths.\n    thread_id : str\n        Target thread.\n    request : Request\n        FastAPI request — used to retrieve singletons from ``app.state``.\n    \"\"\"\n    try:\n        validate_thread_id(thread_id)\n    except ValueError as exc:\n        raise HTTPException(status_code=422, detail=str(exc)) from exc\n\n    body_config = getattr(body, \"config\", None)\n    config_metadata = body_config.get(\"metadata\") if isinstance(body_config, dict) else None\n    try:\n        validate_run_metadata_secrets(getattr(body, \"metadata\", None))\n        validate_run_metadata_secrets(config_metadata)\n    except LegacyRunMetadataSecretError as exc:\n        raise HTTPException(status_code=422, detail=str(exc)) from exc\n\n    stream_modes = normalize_stream_modes(body.stream_mode)\n    bridge = get_stream_bridge(request)\n    run_mgr = get_run_manager(request)\n    run_ctx = get_run_context(request)\n\n    disconnect = DisconnectMode.cancel if body.on_disconnect == \"cancel\" else DisconnectMode.continue_\n\n    body_context = getattr(body, \"context\", None) or {}\n    model_name = body_context.get(\"model_name\")","sourceCodeStart":1051,"sourceCodeEnd":1087,"githubUrl":"https://github.com/bytedance/deer-flow/blob/1dd6ba1acb03700589994b0366c5d1c7d05e2eff/backend/app/gateway/services.py#L1051-L1087","documentation":"HTTP 422 raised when validate_thread_id rejects the thread_id on a run launch (shared by HTTP and internal launch paths). The ValueError text from the validator becomes the detail, naming the concrete format problem. Thread ids must match the gateway's expected id format before any run is created.","triggerScenarios":"Creating a run with a thread id of the wrong shape/length/charset — e.g. a client-generated random string that violates the id format, an empty id, or an id with characters the validator forbids.","commonSituations":"Clients minting their own thread ids instead of creating threads via the API; URL-decoded ids that lost/gained characters; porting code from another platform with laxer id rules.","solutions":["Create the thread through the threads API first and use the returned id verbatim for runs.","Read the detail string — it is the validator's own message describing the expected format.","Validate/normalize ids client-side (no whitespace, correct casing) before sending."],"exampleFix":"# before\nruns.post(\"/threads/my-thread/runs\", payload)\n\n# after\nthread = threads.post({})  # gateway assigns a valid id\nruns.post(f\"/threads/{thread.thread_id}/runs\", payload)","handlingStrategy":"validation","validationCode":"const thread = await fetch('/api/threads', {method: 'POST'}).then(r => r.json());\nconst tid = thread.thread_id; // use gateway-issued id only","typeGuard":"const isServerIssuedThreadId = (id: unknown): id is string =>\n  typeof id === 'string' && id.length > 0 && /^[0-9a-fA-F-]+$/.test(id) && !id.includes(' ');","tryCatchPattern":"catch 422 on run creation; the detail carries the validator's format message — fix the id (usually by creating the thread properly) rather than retrying.","preventionTips":["Never mint thread ids client-side; create threads via the API.","Pass ids through verbatim without trimming/re-encoding.","On 422, read the detail: it states the expected id format."],"tags":["runs","http-422","thread-id","validation"],"backgroundTag":null,"analyzedSha":"1dd6ba1acb03700589994b0366c5d1c7d05e2eff","analyzedAt":"2026-08-14T21:20:34.804Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}