Comfy-Org/ComfyUI · error · UploadError

HASH_CHECK_FAILED

HASH_CHECK_FAILED

Error message

Backend error while checking asset hash.

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 a JSON dict without a recognizable error.message structure — the entire body is serialized: 'API Error: {json.dumps(body)}'. This is the fallback for structured JSON error payloads the formatter does not specifically understand.

Source

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

        fname = getattr(field, "name", "") or ""

        if fname == "hash":
            try:
                s = ((await field.text()) or "").strip().lower()
            except Exception:
                raise UploadError(
                    400, "INVALID_HASH", "hash must be like 'blake3:<hex>'"
                )

            if s:
                provided_hash = normalize_and_validate_hash(s)
                try:
                    provided_hash_exists = check_hash_exists(provided_hash)
                except Exception as e:
                    logging.exception(
                        "check_hash_exists failed for hash=%s: %s", provided_hash, e
                    )
                    raise UploadError(
                        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:

View on GitHub (pinned to 1c6d8d45b3)

Solutions

1. Parse the dumped JSON in the message to find the provider's actual error field (detail, errors, message elsewhere)
2. Fix the underlying cause indicated by that body
3. If integrating a new provider, normalize its error schema at the node boundary or extend _friendly_http_message to parse it
4. Use the logged response (status + body) as the source of truth

def extract_provider_error(e_msg: str) -> dict | None:
    if e_msg.startswith("API Error: "):
        try:
            return json.loads(e_msg[len("API Error: "):])
        except json.JSONDecodeError:
            return None
    return None

try:
    result = await sync_op(...)
except Exception as e:
    body = extract_provider_error(str(e))
    reason = (body or {}).get("detail") or (body or {}).get("errors")
    if reason:
        handle(reason)
    else:
        raise

When it happens

Trigger: Providers using nonstandard error schemas (e.g. {"detail": ...}, {"errors": [...]}, plain status objects) on a >=400 response; gateway-produced JSON error bodies; validation error arrays from framework defaults (FastAPI-style detail).

Common situations: Custom/newly integrated provider nodes whose error schema was never mapped; provider migrations changing error formats; upstream proxies injecting JSON errors.

Related errors

• UNSUPPORTED_MEDIA_TYPE
• UPLOAD_IO_ERROR
• 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/6220001e1d9456f9. Report an issue: GitHub.