Skip to content

Revision 1 — the current text. The evidence on this page is this revision’s own — it has not been carried forward from, or to, any other revision.

Fixing 'no configuration file provided: not found' after migrating to Compose V2

Covers Compose V2's default file-discovery rule and the invocation mismatches that commonly break after a V1-to-V2 migration. Does not cover Compose file syntax/schema errors once a file is actually found and parsed.

Docker Compose
Unverifiedno reproductions yetWhy this confidence?
Revision 1published by DevYou curation

Where this applies

Tell us your versions and this page will say whether it applies to you.

Symptoms

The diagnostic path

9 steps, exactly as this revision published them.

  1. Step 1 · StartCompose V2 can't find a configuration file

    Compose V2 is a docker CLI plugin (docker compose), not the old standalone docker-compose binary, and it is stricter about failing loudly rather than searching parent directories the way some V1 setups did.

    What happens next

    • passed → step 2, Is there actually a compose file in the current working directory?

  2. Step 2 · TestIs there actually a compose file in the current working directory?

    Compose V2 looks only for these four names, in this directory, by default.

    Read-onlybash
    ls -1 compose.yaml compose.yml docker-compose.yaml docker-compose.yml 2>/dev/null

    Expected result

    docker-compose.yml

    What happens next

    • passed → step 3, Is the command run from the file's directory, with no conflicting -f pointing elsewhere?
    • failed → step 4, No compose file exists under any of the four default names
    • unknown → step 4, No compose file exists under any of the four default names

  3. Step 3 · TestIs the command run from the file's directory, with no conflicting -f pointing elsewhere?

    V1 scripts/CI steps sometimes relied on an implicit working directory, or an old -f path baked into a wrapper script, that Compose V2 doesn't replicate the same way.

    What happens next

    • passed → step 5, Invocation and file placement look correct
    • failed → step 6, The command isn't being run from where the file actually lives
    • unknown → step 6, The command isn't being run from where the file actually lives

  4. Step 4 · Root causeNo compose file exists under any of the four default names

    If your file is named something else — e.g. docker-compose.local.yml — Compose V2 will never find it automatically; it must be passed explicitly with -f.

    What happens next

    • passed → step 7, Run from the right directory, or pass the file explicitly

  5. Step 5 · Root causeInvocation and file placement look correct

    Check file permissions, whether it's a broken symlink, or whether a CI checkout step skipped it (e.g. via .dockerignore or a sparse checkout) — outside this playbook's scope beyond flagging it.

  6. Step 6 · Root causeThe command isn't being run from where the file actually lives

    The script or CI step's working directory changed, or it's using a leftover -f path from before the migration.

    What happens next

    • passed → step 7, Run from the right directory, or pass the file explicitly

  7. Step 7 · FixRun from the right directory, or pass the file explicitly

    Point -f directly at the file rather than relying on the default discovery.

    Changes statebash

    Changes system or service state. Review before running.

    Starts (or recreates) the containers defined in the given compose file, in detached mode. Existing containers for this project may be stopped and replaced; named volumes are preserved.

    docker compose -f ./deploy/docker-compose.yml up -d

    What happens next

    • passed → step 8, Confirm compose finds and parses the file

  8. Step 8 · Verify the fixConfirm compose finds and parses the file

    This renders the fully merged configuration without starting anything, and fails the same way up would if the file still isn't found.

    Read-onlybash
    docker compose config

    Expected result

    services:
  api:
    image: app/api:latest
    ports:
      - "3000:3000"

    What happens next

    • passed → step 9, Resolved
    • failed → step 5, Invocation and file placement look correct
    • unknown → step 5, Invocation and file placement look correct

  9. Step 9 · EndResolved

    Compose finds and parses the file from this invocation.

Sources

Why this confidence?

What would strengthen it: 6 more independent reproductions. Reproductions from 3 more distinct environments.

This counts only what was recorded against revision 1 itself. Nothing reported against another revision is included here — see the revision history for why.