ErrLookup › Background articles › "Config file not found": what it means and how to fix it in docker-sync, Maven, Vagrant, Turborepo and other tools

"Config file not found": what it means and how to fix it in docker-sync, Maven, Vagrant, Turborepo and other tools

"Config file not found" errors appear when a CLI, server, or library tries to load a configuration file — by explicit path, well-known default, or directory traversal — and the file does not exist or cannot be read at the resolved path. This guide covers why the path resolution surprises you (cwd-relative paths, parent-directory searches, container mounts), the common variants of the error across 60+ open-source projects, and the fixes that hold across the family.

Distilled from 97 documented records across 60 repositories.

Background

This family covers every error a tool raises when the configuration file it needs is not present at the path it resolved. The triggering layer is almost always the very first step of startup: before any parsing, validation, or business logic runs, the code does a stat, exists(), isFile(), or read call on a config path and fails. Because it fires before anything else, you get a terse, path-centric message — 'configuration file not found', 'File /path/x.json does not exist.', 'No docker-sync.yml configuration found in your path' — instead of a stack trace from deeper inside.

The key thing the records reveal is that 'the path it resolved' is rarely just the string you typed. Libraries resolve the path differently, and that resolution is where most confusion lives. Some expand relative paths against the current working directory (Maven's -t, -ps, and -is options; Turborepo's --config; linera-exporter's --config). Others expand against a project root instead of cwd: Vagrant expands chef.validation_key_path against machine.env.root_path (the Vagrantfile's directory), so a relative path that 'looks right' from your shell resolves elsewhere. Docker-sync and Hasura's GraphQL engine walk upward from the current directory through every ancestor looking for an exact filename, so the file must sit in the current directory or a parent — and the lookup is exact-name only (docker-sync.yml will not match docker-sync.yaml). Others combine markers and defaults: claude-task-master only complains about a derived root if it looks like a project (.taskmaster/ exists) but the config inside is missing, while golangci-lint's custom builder does the opposite — no parent search at all, only the exact .custom-gcl.{yml,yaml,json} in the current directory.

Whether a missing file is a hard error or a soft fallback is library-specific, and even within one library it depends on how the path was supplied. Repomix treats an explicit --config as the user's intentional choice and fails hard, but silently falls back to discovery when no flag is given. Task Master downgrades a missing config to a warning plus defaults. Tailscale's conffile.Load wraps read-phase failures in a sentinel (ErrNoConfig) so callers can distinguish 'absent' from 'read but unparseable', and its optional: config prefix makes absence acceptable. Presto treats an unreadable password file as CONFIGURATION_UNAVAILABLE — a server configuration problem, not an authentication failure — so every auth through that store fails until the file is readable. Cilium's Hubble metrics watcher keeps the last good config and retries on the next filesystem event. And Teleport's updater distinguishes an expected absence (Kubernetes upgraders skip updater info when errors.Is(err, ErrConfigNotFound)) from a real problem.

Some members of the family are not strictly 'not found' at all: Go's rbac.LoadPermissions and Cilium both wrap the raw OS error with %w, so the message tells you whether it was no-such-file, permission-denied, or is-a-directory. Oh-my-pi splits explicitly: ENOENT yields 'Config overlay not found', anything else yields 'Failed to read config overlay' with the underlying error. Reading the exact wording matters, because permission problems and wrong-cwd resolution masquerade as missing files.

Common causes

What usually fixes it

Documented occurrences

…and 77 more across the corpus — use search.

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