ErrLookup › Background articles › FileNotFoundError in Python: missing model weights, config files, and paths that only look like file problems

FileNotFoundError in Python: missing model weights, config files, and paths that only look like file problems

FileNotFoundError is Python's built-in signal that a path expected on disk does not exist — but in practice it fires far beyond typos. Across the 249 documented records in this family, it most often appears when machine-learning weights were never downloaded (offline hosts, blocked egress to huggingface.co or modelscope.cn), when settings or .env files are absent at startup, when a renamed or mis-cased file defeats filename-based dispatch, or when a failed network fetch is wrapped and re-raised as this error even though no file was ever involved. Developers meet it on first run of a model, in air-gapped deployments, and in long training jobs whose dataset paths resolve against the wrong base directory.

Distilled from 249 documented records across 67 repositories.

Background

FileNotFoundError (OSError subclass, errno ENOENT) is raised by the interpreter and by explicit `raise FileNotFoundError(...)` guards in library code, and this family spans both origins. The explicit-raise variant dominates the records: libraries deliberately choose this exception to mean "a required artifact is not where the loader resolved it", even when the root cause is upstream. Docling, Deep-Live-Cam, MinerU, immich, and headroom all raise it after a download attempt fails or is skipped, embedding the resolved path and sometimes a prefetch command in the message. From the caller's side it looks identical to a typo'd path, which is why the better-engineered messages (ultralytics's data-loading wrapper, sherlock's manifest fetch, headroom's ONNX candidate loop) insist that you read the chained exception, print the searched locations, or list what actually is on disk.

The largest cluster is ML model artifacts. Weights live on remote hubs (HuggingFace, ModelScope, project-specific URLs) and land in local caches with strict layouts — `models--<org>--<repo>` folders, exact filenames like `gfpgan-1024.onnx`, or paired files like Paddle's required `.json` + `.pdiparams`. The error fires when the artifact was never fetched (offline, no egress, dead URL, unwritable cache), was fetched into a different cache directory than the loader reads, or was fetched in a variant the loader cannot use (an int8 ONNX model an onnxruntime build rejects at execution; an artifact set downloaded for the wrong backend/language pair). LoRA checkpoints add a special case: adapter deltas require the base model to merge into, so a present-but-incomplete model directory still fails.

A second cluster is configuration and derived-data files: settings.yaml profiles resolved by naming convention (private-gpt), .env files located relative to the notebook kernel's cwd (hello-agents), and training-time serialization artifacts like author_map.pkl and file_map.pkl that must match the model checkpoint exactly and cannot be regenerated without corrupting inference. A third cluster is filename-as-API dispatch: ultralytics's build_sam selects an architecture by exact checkpoint suffix, OpenMontage resolves pipelines, schemas, and playbooks by `{name}.yaml` stem lookups, and appending `.yaml` yourself or wrong casing produces a miss. Finally, some FileNotFoundErrors are not about files at all: sherlock wraps any requests failure (DNS, proxy, SSL, timeout) as FileNotFoundError, and yarp's .deb extractor rejects an HTML error page saved with a .deb extension because no `data.tar` member exists — network failures wearing a file error's clothes.

The family also includes concurrency and wrapper shapes: graphify catches the file vanishing between a prior stat and the current one during concurrent rebuilds, and ultralytics's yolov5 data loader re-wraps every scanning failure (permissions, empty directories, encoding errors in list files) as FileNotFoundError with the original chained as __cause__. Where records disagree — e.g. whether a loader auto-downloads (GPEN enhancers do, GFPGAN does not) — the behavior is library-specific, so the fix always starts with checking that specific loader's contract.

Common causes

What usually fixes it

Go deeper

Documented occurrences

…and 229 more across the corpus — use search.

Honest provenance: generated on 2026-08-15 from AI-assisted analysis of the linked records. See how records are made.