lllyasviel/Fooocus · error · RuntimeError

checkpoint url or path is invalid

Error message

checkpoint url or path is invalid

What it means

Raised by BLIP's load_checkpoint when the url_or_filename argument is neither an http/https URL (checked via urlparse scheme) nor an existing local file (os.path.isfile). It is the final else branch after both checkpoint-loading routes fail, so it always means the checkpoint location string is wrong or the file is missing at that path.

Source

Thrown at extras/BLIP/models/blip.py:223

        vision_width = 1024
        visual_encoder = VisionTransformer(img_size=image_size, patch_size=16, embed_dim=vision_width, depth=24, 
                                           num_heads=16, use_grad_checkpointing=use_grad_checkpointing, ckpt_layer=ckpt_layer,
                                           drop_path_rate=0.1 or drop_path_rate
                                          )   
    return visual_encoder, vision_width

def is_url(url_or_filename):
    parsed = urlparse(url_or_filename)
    return parsed.scheme in ("http", "https")

def load_checkpoint(model,url_or_filename):
    if is_url(url_or_filename):
        cached_file = download_cached_file(url_or_filename, check_hash=False, progress=True)
        checkpoint = torch.load(cached_file, map_location='cpu', weights_only=True) 
    elif os.path.isfile(url_or_filename):        
        checkpoint = torch.load(url_or_filename, map_location='cpu', weights_only=True) 
    else:
        raise RuntimeError('checkpoint url or path is invalid')
        
    state_dict = checkpoint['model']
    
    state_dict['visual_encoder.pos_embed'] = interpolate_pos_embed(state_dict['visual_encoder.pos_embed'],model.visual_encoder) 
    if 'visual_encoder_m.pos_embed' in model.state_dict().keys():
        state_dict['visual_encoder_m.pos_embed'] = interpolate_pos_embed(state_dict['visual_encoder_m.pos_embed'],
                                                                         model.visual_encoder_m)    
    for key in model.state_dict().keys():
        if key in state_dict.keys():
            if state_dict[key].shape!=model.state_dict()[key].shape:
                del state_dict[key]
    
    msg = model.load_state_dict(state_dict,strict=False)
    print('load checkpoint from %s'%url_or_filename)  
    return model,msg
    

View on GitHub (pinned to ae05379cc9)

Solutions

1. Verify the file exists at the exact path passed: os.path.isfile(your_path); if not, correct the path or use an absolute path via os.path.abspath / pathlib.Path(...).resolve()
2. If passing a URL, ensure it starts with http:// or https:// (the is_url helper only accepts those schemes) and that the URL is reachable
3. Download the pretrained checkpoint manually (e.g. from the BLIP release URLs) into your checkpoints directory and pass that local path
4. Check for leading/trailing whitespace, quotes, or 'file://' prefixes in the config value that supplies url_or_filename

Example fix

// before
load_checkpoint(model, 'checkpoints/base_caption.pth')  # file not there

// after
from pathlib import Path
ckpt = Path('checkpoints/base_caption.pth').resolve()
assert ckpt.is_file(), f'checkpoint not found: {ckpt}'
load_checkpoint(model, str(ckpt))

from pathlib import Path
from urllib.parse import urlparse

def valid_checkpoint_target(s):
    if not isinstance(s, str) or not s.strip():
        return False
    if urlparse(s).scheme in ('http', 'https'):
        return True
    return Path(s).expanduser().is_file()

def is_loadable_checkpoint(s: str) -> bool:
    return valid_checkpoint_target(s)

try:
    load_checkpoint(model, ckpt)
except RuntimeError as e:
    if 'checkpoint url or path is invalid' in str(e):
        raise FileNotFoundError(f'checkpoint not found: {ckpt!r}') from e
    raise

When it happens

Trigger: Calling load_checkpoint(model, path) with a misspelled relative path, a path relative to a different working directory, a file:// or s3:// style URL (scheme is not http/https), an ftp URL, or a local path that was never downloaded/moved. Also triggered by passing None or an empty string.

Common situations: Running BLIP training/eval scripts from a different cwd so relative checkpoint paths break; copying configs that reference pretrained weights like 'checkpoints/model_base_capfilt_large.pth' that were never downloaded; typos in the checkpoint filename; using an environment without internet so the cached download directory never got populated.

Related errors

• checkpoint url or path is invalid
• The hidden size (%d) is not a multiple of the number of atte
• The hidden size (%d) is not a multiple of the number of atte
• Max depth of recursive function `tie_encoder_to_decoder` rea
• Wrong shape for input_ids (shape {}) or attention_mask (shap

AI-assisted analysis of lllyasviel/Fooocus@ae05379cc9 (2026-08-15). Data as JSON: /api/errors/ea647035fa1ab74b. Report an issue: GitHub.