Comfy-Org/ComfyUI · error · OSError

hash of {path} (url: {url}) failed to validate

Error message

hash of {path} (url: {url}) failed to validate

What it means

Raised by comfy/k_diffusion/utils.py's download_file() helper after a file (already on disk or just downloaded) fails SHA-256 validation against the caller-supplied digest. It is an OSError, signalling the local bytes do not match the expected checksum for the given URL. Typical root cause is a truncated/corrupted prior download, a proxy or CDN serving different content, or an incorrect digest string.

Source

Thrown at comfy/k_diffusion/utils.py:47

    return expanded.detach().clone() if expanded.device.type == 'mps' else expanded


def n_params(module):
    """Returns the number of trainable parameters in a module."""
    return sum(p.numel() for p in module.parameters())


def download_file(path, url, digest=None):
    """Downloads a file if it does not exist, optionally checking its SHA-256 hash."""
    path = Path(path)
    path.parent.mkdir(parents=True, exist_ok=True)
    if not path.exists():
        with urllib.request.urlopen(url) as response, open(path, 'wb') as f:
            shutil.copyfileobj(response, f)
    if digest is not None:
        file_digest = hashlib.sha256(open(path, 'rb').read()).hexdigest()
        if digest != file_digest:
            raise OSError(f'hash of {path} (url: {url}) failed to validate')
    return path


@contextmanager
def train_mode(model, mode=True):
    """A context manager that places a model into training mode and restores
    the previous mode on exit."""
    modes = [module.training for module in model.modules()]
    try:
        yield model.train(mode)
    finally:
        for i, module in enumerate(model.modules()):
            module.training = modes[i]


def eval_mode(model):
    """A context manager that places a model into evaluation mode and restores
    the previous mode on exit."""

View on GitHub (pinned to 1c6d8d45b3)

Solutions

  1. Delete the partial/corrupt file at {path} (and any siblings) so download_file re-downloads it fresh
  2. Recompute sha256 of the file (shasum -a 256 / certutil -hashfile) and compare with the expected digest to confirm corruption vs. wrong digest
  3. Verify the URL still serves the intended artifact and that the digest matches the publisher's stated hash; update digest if the artifact legitimately changed
  4. If behind a proxy/cache, bypass it or clear it and retry the download manually before re-running

Example fix

# before: corrupt cached file keeps failing
# rm the cached file so it re-downloads
import os; os.remove('/path/to/model/file')

# after: validate before passing digest
d = hashlib.sha256(open(path,'rb').read()).hexdigest()
if d != expected: os.remove(path)
path = download_file(path, url, digest=expected)
Defensive patterns

Strategy: retry

Validate before calling

import hashlib, os
def ensure_file(path, url, digest):
    if os.path.exists(path):
        d = hashlib.sha256(open(path,'rb').read()).hexdigest()
        if d != digest:
            os.remove(path)  # force clean re-download
    return download_file(path, url, digest=digest)

Try / catch

try:
    path = download_file(p, url, digest=d)
except OSError as e:
    if 'failed to validate' in str(e):
        os.remove(p)
        path = download_file(p, url, digest=d)  # one clean retry
    else:
        raise

Prevention

When it happens

Trigger: Calling download_file(path, url, digest=...) where the file already exists (or downloads) and hashlib.sha256 of its contents != digest. Happens when a previous run was interrupted mid-write leaving a partial file, or when the URL points to a re-published artifact whose hash changed.

Common situations: Corrupted cache from a killed process or disk-full event; the upstream file at the URL was replaced; a typo'd or copy-paste-mangled digest; a mirror/proxy injecting an HTML error page instead of the binary.

Related errors

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