What causes "env file %s not found" in docker/compose?

Create the missing file at the exact path shown in the error, or copy it from your template (cp .env.example .env).

env file %s not found

Error message

env file %s not found

What it means

The pre-publish secret scan found a service env_file that does not exist on disk and is marked required (required: true, or defaulted as required by the loader). Required env files must be present so their contents can be scanned; a missing one aborts the publish.

Source

Thrown at pkg/compose/publish.go:711

		if err != nil {
			return nil, err
		}

		findings, err := scan.ScanReader(in)
		if err != nil {
			return nil, fmt.Errorf("failed to scan compose file %s: %w", file, err)
		}
		allFindings = append(allFindings, findings...)
	}
	for _, service := range project.Services {
		// Check env files
		for _, envFile := range service.EnvFiles {
			if _, statErr := os.Stat(envFile.Path); statErr != nil {
				if !os.IsNotExist(statErr) {
					return nil, fmt.Errorf("failed to access env file %s: %w", envFile.Path, statErr)
				}
				if envFile.Required {
					return nil, fmt.Errorf("env file %s not found", envFile.Path)
				}
				continue
			}
			findings, err := scan.ScanFile(envFile.Path)
			if err != nil {
				return nil, fmt.Errorf("failed to scan env file %s: %w", envFile.Path, err)
			}
			allFindings = append(allFindings, findings...)
		}
	}

	// Check configs defined by files
	for _, config := range project.Configs {
		if config.File != "" {
			findings, err := scan.ScanFile(config.File)
			if err != nil {
				return nil, fmt.Errorf("failed to scan config file %s: %w", config.File, err)
			}

View on GitHub (pinned to ddc4b044b6)

Solutions

Create the missing file at the exact path shown in the error, or copy it from your template (cp .env.example .env).
If the file is intentionally optional, declare it with required: false in the compose file.
Fix the path if it is a typo or resolved against the wrong working directory (relative paths resolve from the compose file's directory).
In CI, ensure the env file step (secret injection) runs before docker compose publish.

Example fix

# before
services:
  api:
    env_file:
      - ./.env.prod    # missing, required by default

# after (optional file)
services:
  api:
    env_file:
      - path: ./.env.prod
        required: false

Defensive patterns

Strategy: validation

Validate before calling

func requireEnvFiles(project *types.Project) error {
	for _, svc := range project.Services {
		for _, ef := range svc.EnvFiles {
			if !ef.Required {
				continue
			}
			if _, err := os.Stat(ef.Path); errors.Is(err, fs.ErrNotExist) {
				return fmt.Errorf("required env file %s missing", ef.Path)
			}
		}
	}
	return nil
}

Try / catch

if err := publish(ctx, opts); err != nil {
    if strings.Contains(err.Error(), "env file") && strings.Contains(err.Error(), "not found") {
        // create the file from template or mark required: false, retry
    }
    return err
}

Prevention

Commit .env templates and add a CI check that required env files exist.
Mark truly optional env files with required: false.
Resolve relative env_file paths against the compose file's directory to avoid working-dir drift.

When it happens

Trigger: Publishing a project where a service declares env_file: ./prod.env (or an entry with required: true) and the file is absent at scan time. Optional files (required: false) are skipped silently instead.

Common situations: Env files excluded by .gitignore so teammates/CI lack them; deploying from a fresh checkout without copying the env template; path typos; the file living outside the build context in CI.

Related errors

AI-assisted analysis of docker/compose@ddc4b044b6 (2026-08-15). Data as JSON: /api/errors/ef99addcc0bd1e46. Report an issue: GitHub.