What causes "specify a Compose file (with --compose-file)" in docker/cli?

Provide a Compose file: `docker stack deploy -c compose.yml mystack`.

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

Error message

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

What it means

Thrown by getConfigDetails (cli/command/stack/loader.go:90) when the composefiles slice is empty. Deploying a stack requires a Compose specification to translate into swarm services/networks; with no `--compose-file` provided there is literally nothing to parse or deploy.

Solutions

Provide a Compose file: `docker stack deploy -c compose.yml mystack`.
Stream via stdin: `docker stack deploy -c - mystack < compose.yml`.
Validate that the file variable is set in scripts before invoking deploy.

Example fix

// before
docker stack deploy mystack

// after
docker stack deploy -c docker-compose.yml mystack
# or from stdin:
cat docker-compose.yml | docker stack deploy -c - mystack

Defensive patterns

Strategy: validation

Validate before calling

if len(composeFiles) == 0 {
	return errors.New("no Compose file provided; pass --compose-file / -c")
}

Prevention

Fail scripts early if the compose-file variable is unset.
Default to an explicit `-c` in CI rather than relying on memory.
Validate the file exists and is readable before deploy.

When it happens

Trigger: Running `docker stack deploy mystack` without any `-c`/`--compose-file` argument, so `len(composefiles) == 0`.

Common situations: Forgot the flag interactively; a script/build step that drops `-c` due to an unset variable; expecting a default compose file that the CLI does not assume.

Related errors

AI-assisted analysis of docker/cli@4f84911bfe (2026-08-07). Data as JSON: /api/errors/f2d7b7a241a5ef45. Report an issue: GitHub.

Appendix: 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 4f84911bfe)