docker/cli · error

specify a Compose file (with --compose-file)

Error message

specify a Compose file (with --compose-file)

What it means

Emitted by `docker stack deploy` (and `docker stack config`) when no Compose file was supplied. getConfigDetails (loader.go:86-91) is called with the list of --compose-file/-c values; an empty list means the CLI has nothing to load, so it fails immediately rather than guessing a default file.

Source

Thrown at cli/command/stack/loader.go:90

	return dicts
}

func propertyWarnings(properties map[string]string) string {
	msgs := make([]string, 0, len(properties))
	for name, description := range properties {
		msgs = append(msgs, fmt.Sprintf("%s: %s", name, description))
	}
	sort.Strings(msgs)
	return strings.Join(msgs, "\n\n")
}

// getConfigDetails parse the composefiles specified in the cli and returns their ConfigDetails
func getConfigDetails(composefiles []string, stdin io.Reader) (composetypes.ConfigDetails, error) {
	var details composetypes.ConfigDetails

	if len(composefiles) == 0 {
		return details, errors.New("specify a Compose file (with --compose-file)")
	}

	if composefiles[0] == "-" && len(composefiles) == 1 {
		workingDir, err := os.Getwd()
		if err != nil {
			return details, err
		}
		details.WorkingDir = workingDir
	} else {
		absPath, err := filepath.Abs(composefiles[0])
		if err != nil {
			return details, err
		}
		details.WorkingDir = filepath.Dir(absPath)
	}

	var err error
	details.ConfigFiles, err = loadConfigFiles(composefiles, stdin)

View on GitHub (pinned to e9452d6e78)

Solutions

1. Pass the file explicitly: `docker stack deploy -c docker-compose.yml mystack`
2. To read from stdin, use `-c -` (e.g. `docker compose config | docker stack deploy -c - mystack`)
3. Multiple files can be layered with repeated -c flags: `-c base.yml -c prod.yml`

Example fix

# before
docker stack deploy mystack
# specify a Compose file (with --compose-file)

# after
docker stack deploy -c docker-compose.yml mystack

When it happens

Trigger: `docker stack deploy mystack` with no -c/--compose-file flag; scripts where the variable holding the compose path expands to empty so the flag is never passed.

Common situations: Expecting docker-compose.yml to be picked up implicitly like `docker compose up` does — `docker stack deploy` has no default file; shell variable typos ($COMPOSE_FILE unset); migrating docker-compose commands to stack deploy without adding the flag.

Related errors

• replicas can only be used with replicated or replicated-job
• replicas-max-per-node can only be used with replicated or re
• max-concurrent can only be used with replicated-job mode
• update and rollback configuration is not supported for jobs
• cannot get label %s for service %s

AI-assisted analysis of docker/cli@e9452d6e78 (2026-08-01). Data as JSON: /data/errors/f2d7b7a241a5ef45.json. Report an issue: GitHub.