{"record":{"id":"ef8fdc2242270363","repo":"calesthio/OpenMontage","slug":"tokenhub-task-task-id-failed-error-msg","errorCode":null,"errorMessage":"TokenHub task {task_id} failed: {error_msg}","messagePattern":"TokenHub task (.+?) failed: (.+?)","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"tools/graphics/hunyuan_image.py","lineNumber":511,"sourceCode":"            )\n            data = self._json_or_raise(resp)\n            self._check_response(data)\n\n            status = data.get(\"status\", \"\")\n\n            if status == \"completed\":\n                result_data = data.get(\"data\") or []\n                urls = [item.get(\"url\") for item in result_data if item.get(\"url\")]\n                if not urls:\n                    raise RuntimeError(\n                        f\"TokenHub task {task_id} completed but no data[].url: {data}\"\n                    )\n                return urls\n\n            if status == \"failed\":\n                error_info = data.get(\"error\") or {}\n                error_msg = error_info.get(\"message\", \"unknown error\")\n                raise RuntimeError(\n                    f\"TokenHub task {task_id} failed: {error_msg}\"\n                )\n\n            # queued / running / in_progress — continue polling\n            if status not in (\"queued\", \"running\", \"in_progress\"):\n                raise RuntimeError(\n                    f\"TokenHub task {task_id} returned unknown status: {status}\"\n                )\n\n        raise TimeoutError(\n            f\"TokenHub task {task_id} did not finish within {timeout_seconds}s\"\n        )\n\n    # ------------------------------------------------------------------\n    # Error handling helpers\n    # ------------------------------------------------------------------\n\n    @staticmethod","sourceCodeStart":493,"sourceCodeEnd":529,"githubUrl":"https://github.com/calesthio/OpenMontage/blob/95e1c3d0ab93482159818560f6a8c8e866b9139f/tools/graphics/hunyuan_image.py#L493-L529","documentation":"RuntimeError raised when the polled TokenHub task reaches status 'failed'. The poller extracts error.message from the task payload (defaulting to 'unknown error' when absent) and surfaces it to the caller; this is the provider's own failure report, not a client-side error.","triggerScenarios":"Any Hunyuan image generation the upstream service rejects or crashes on: content moderation, invalid parameters accepted at submit time, upstream GPU failures, or quota exhaustion mid-job.","commonSituations":"Prompts with policy-violating content; rare transient upstream failures that succeed on retry; hitting a concurrent-task limit that manifests as a failed status rather than an HTTP error.","solutions":["Read the embedded error_msg — it is the provider's reason and dictates the fix","For content errors, rephrase the prompt and remove disallowed elements","For transient/unknown errors, retry once after a short delay before escalating","Check the TokenHub console for account quota and concurrency limits"],"exampleFix":null,"handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"import time\nfor attempt in range(2):\n    try:\n        urls = client._poll_task(task_id, ...)\n        break\n    except RuntimeError as e:\n        if \"failed:\" in str(e) and \"unknown error\" in str(e) and attempt == 0:\n            time.sleep(5)  # one retry for opaque transient failures\n            continue\n        raise","preventionTips":["Surface error_msg to logs so root cause is never lost","Retry only opaque/'unknown error' failures; content errors need prompt changes","Monitor quota/concurrency so failures are predictable"],"tags":["hunyuan","tokenhub","async-job","api-error"],"backgroundTag":null,"analyzedSha":"95e1c3d0ab93482159818560f6a8c8e866b9139f","analyzedAt":"2026-08-15T06:31:20.014Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}