Practical AI Guides

English

简体中文

English

简体中文

Appearance

Model Loading Failed: Not Found, Not Recognized, Architecture Mismatch ​

ComfyUI Model loading failures generally fall into three categories: file not found, file not recognized, and architecture mismatch. The troubleshooting directions for these three problems are completely different. First determine which category you fall into, then follow the three steps below—don't jump straight to re-downloading. Before starting, it's recommended to go through the 60-second quick check in the troubleshooting overview.

Symptoms ​

Compare your situation against the three manifestations below to determine your problem type:

  • The node's model dropdown list is empty, or a model you just placed doesn't appear—most likely a path issue.
  • At runtime it reports Value not in list: ckpt_name: 'model-name.safetensors' not in [] (specified model not found)—the file is not in the search path.
  • During generation it reports errors like tensor dimension or shape mismatch—architecture mismatch.

Quick Check (60 seconds) ​

  1. Is the file in the subdirectory for its corresponding type under ComfyUI/models/? Checkpoints go in checkpoints/, LoRAs in loras/, VAEs in vae/.
  2. Is the extension in ComfyUI's supported list (most commonly .safetensors / .ckpt)? Does the file size match the official release page?
  3. Click the Refresh button in the interface once, or restart ComfyUI, then check the dropdown list again.

Troubleshooting Steps ​

Step 1: Confirm the search path ​

Error: Value not in list: ckpt_name: 'model-name.safetensors' not in [] (specified model not found) ​

Solution: Put the model in the subdirectory for its corresponding type, or let ComfyUI read your custom directory. Placing a file in the wrong type directory is the most common cause—a checkpoint placed in loras/ naturally won't appear in the dropdown list. If you keep your models on another disk, you need to register the extra search path in extra_model_paths.yaml (see Where to Put Models: models Directory and extra_model_paths Explained for configuration syntax); restart ComfyUI after changes for them to take effect.

Step 2: Confirm the file is complete and in the correct format ​

Error: Error while deserializing header (model file cannot be recognized / loading result is empty) ​

Solution: Suspect the file itself first—re-download it and verify the file size. An interrupted download leaves behind a corrupted file; confirm the extension is in ComfyUI's supported list (.safetensors, .ckpt, .pt, .pth, .bin, etc.; see Where to Put Models for the complete list); if the filename contains special characters or Chinese, rename it to plain English letters and numbers, then refresh the list @@I18N_KEEP_000014@@.

Step 3: Handle architecture mismatch ​

Error: The size of tensor a (49) must match the size of tensor b (16) at non-singleton dimension 1 (tensor dimension / shape mismatch) ​

Solution: This type of error means the model architecture doesn't match the loader—the file isn't broken. There are three common scenarios: using a generic checkpoint loader to load a model containing only partial weights—you should switch to the corresponding dedicated loader node (see the mapping table in Where to Put Models for the loader node corresponding to each model type); the LoRA and base model have inconsistent architectures—switch to a LoRA with the same architecture; the model is too new and your current ComfyUI version may not yet support its architecture—update to the latest version and try again. A misconfigured VAE can also report a channel count mismatch; for example, using sdxl_vae.safetensors with a Flux model—switching to ae.safetensors from the official Flux release resolves it. First check the architecture noted on the model's release page, then choose a matching loader.

When to Escalate ​

If any of the following occurs, stop grinding away locally and file an issue on ComfyUI's GitHub repository:

  • After switching to the correct loader and directory, it still reports tensor dimension errors.
  • The same model file loads fine in other tools; only ComfyUI reports the error.
  • The problem persists after re-downloading; the model file itself may be faulty.

When filing an issue, attach: the complete error text, the model name and download source, and your ComfyUI version and startup method.

Related Reading ​