Comfy-Org/ComfyUI · error · UploadError

UPLOAD_IO_ERROR

UPLOAD_IO_ERROR

Error message

Failed to receive uploaded file.

What it means

Raised from the HTTP >=400 branch (comfy_api_nodes/util/client.py:823) via _friendly_http_message when the error body is not a dict (parsed as a JSON list/string or plain text) and its string form is at most 200 characters: 'API Error (raw): {txt}'. The raw body text is passed through so short non-structured error bodies remain readable.

Source

Thrown at app/assets/api/upload.py:103

                        500,
                        "HASH_CHECK_FAILED",
                        "Backend error while checking asset hash.",
                    )

        elif fname == "file":
            file_present = True
            file_client_name = (field.filename or "").strip()

            if provided_hash and provided_hash_exists is True:
                # Hash exists - drain file but don't write to disk
                try:
                    while True:
                        chunk = await field.read_chunk(8 * 1024 * 1024)
                        if not chunk:
                            break
                        file_written += len(chunk)
                except Exception:
                    raise UploadError(
                        500, "UPLOAD_IO_ERROR", "Failed to receive uploaded file."
                    )
                continue

            uploads_root = os.path.join(folder_paths.get_temp_directory(), "uploads")
            unique_dir = os.path.join(uploads_root, uuid.uuid4().hex)
            os.makedirs(unique_dir, exist_ok=True)
            tmp_path = os.path.join(unique_dir, ".upload.part")

            try:
                with open(tmp_path, "wb") as f:
                    while True:
                        chunk = await field.read_chunk(8 * 1024 * 1024)
                        if not chunk:
                            break
                        f.write(chunk)
                        file_written += len(chunk)
            except Exception:

View on GitHub (pinned to 1c6d8d45b3)

Solutions

1. Read the raw text — short errors like 'invalid api key' are usually self-explanatory
2. Fix the stated cause (credentials, permissions, payload)
3. Check the logged status code to map text to the real HTTP semantics
4. If the text is opaque, query the provider's docs for that exact string

try:
    result = await sync_op(...)
except Exception as e:
    if str(e).startswith("API Error (raw): "):
        handle_text(str(e)[len("API Error (raw): "):])
    else:
        raise

When it happens

Trigger: Providers returning short plain-text errors (e.g. 'Forbidden', 'invalid api key') or a JSON string scalar on >=400; minimal gateways that send text bodies; auth layers with terse text denials.

Common situations: Simple REST services without structured error JSON; nginx/envoy short text errors; providers with legacy text error endpoints.

Related errors

• UNSUPPORTED_MEDIA_TYPE
• HASH_CHECK_FAILED
• UNSUPPORTED_FIELD
• EMPTY_UPLOAD
• Sonilo API error ({resp.status}): {msg}

AI-assisted analysis of Comfy-Org/ComfyUI@1c6d8d45b3 (2026-08-14). Data as JSON: /api/errors/70f993861019f487. Report an issue: GitHub.