{"record":{"id":"d31f4bcbd24d5862","repo":"Comfy-Org/ComfyUI","slug":"job-id-must-be-a-string-got-type-value-name","errorCode":null,"errorMessage":"job id must be a string, got {type(value).__name__}","messagePattern":"job id must be a string, got (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"comfy_execution/jobs.py","lineNumber":47,"sourceCode":"    CANCELLED = 'cancelled'\n\n    ALL = [PENDING, IN_PROGRESS, COMPLETED, FAILED, CANCELLED]\n\n\ndef validate_job_id(value) -> str:\n    \"\"\"Validate a client-supplied job (prompt) id.\n\n    Job ids must be UUIDs in the canonical lowercase hyphenated form. The id\n    is stored and compared verbatim everywhere downstream — history keys,\n    websocket events, and /interrupt matching — so accepting another spelling\n    would silently rewrite the client's id and then miss every exact-match\n    lookup. Rejecting loudly beats that.\n\n    Returns the id unchanged. Raises ValueError when the value is not a\n    string in canonical UUID form.\n    \"\"\"\n    if not isinstance(value, str):\n        raise ValueError(f\"job id must be a string, got {type(value).__name__}\")\n    if str(uuid.UUID(value)) != value:\n        raise ValueError(\"job id must be a UUID in canonical lowercase hyphenated form\")\n    return value\n\n\n# Media types that can be previewed in the frontend\nPREVIEWABLE_MEDIA_TYPES = frozenset({'images', 'video', 'audio', '3d', 'text'})\n\n# 3D file extensions for preview fallback (no dedicated media_type exists)\nTHREE_D_EXTENSIONS = frozenset({'.obj', '.fbx', '.gltf', '.glb', '.usdz'})\n\n# Text file extensions for preview fallback (the formats SaveText can produce)\nTEXT_EXTENSIONS = frozenset({'.txt', '.md', '.json'})\n\n\ndef has_3d_extension(filename: str) -> bool:\n    lower = filename.lower()\n    return any(lower.endswith(ext) for ext in THREE_D_EXTENSIONS)","sourceCodeStart":29,"sourceCodeEnd":65,"githubUrl":"https://github.com/Comfy-Org/ComfyUI/blob/1c6d8d45b3693bfbb32385b410d813a7fd6be216/comfy_execution/jobs.py#L29-L65","documentation":"Raised by the job-id validator in comfy_execution/jobs.py when a client-supplied prompt/job id is not a Python str — e.g. an int or None posted via the /prompt API. The engine stores and compares job ids verbatim (history keys, websocket events, /interrupt matching), so it validates shape up front: first a type check (this error), then canonical UUID formatting. Rejecting loudly prevents silent id rewriting that would break every later exact-match lookup.","triggerScenarios":"POSTing to /prompt with client_id/prompt_id as a JSON number (e.g. 12345) or omitting it such that a non-string default reaches the validator; any custom client passing an integer id where the API contract expects the string form of a UUID.","commonSituations":"Script/API clients that generate ids with random.getrandbits or use numeric primary keys and pass them unstringified; JSON serializers configured to coerce UUIDs to something other than strings; older custom frontends unaware of the UUID requirement.","solutions":["Send the id as a string in canonical lowercase hyphenated UUID form: str(uuid.uuid4()) in the client.","If using numeric ids internally, map them to a UUID string for the API call and keep the mapping client-side.","Check the JSON payload with a print/inspect before posting — ensure no int/None sneaks into the id field.","Regenerate the id each queue request rather than reusing stale objects of the wrong type."],"exampleFix":"# before\nclient.queue_prompt(workflow, prompt_id=12345)  # int -> ValueError\n\n# after\nimport uuid\nclient.queue_prompt(workflow, prompt_id=str(uuid.uuid4()))","handlingStrategy":"type-guard","validationCode":"assert isinstance(prompt_id, str), f'prompt_id must be str, got {type(prompt_id).__name__}'","typeGuard":"def is_valid_job_id(v) -> bool:\n    if not isinstance(v, str): return False\n    try: return str(uuid.UUID(v)) == v\n    except ValueError: return False","tryCatchPattern":null,"preventionTips":["Always send prompt ids as str(uuid.uuid4()).","Never pass numeric primary keys directly as prompt ids.","Assert the id type in client code before every queue call."],"tags":["api","jobs","validation","uuid"],"backgroundTag":null,"analyzedSha":"1c6d8d45b3693bfbb32385b410d813a7fd6be216","analyzedAt":"2026-08-14T19:37:18.893Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}