What causes "at least one container must be specified" in docker/compose?

Pass one or more running container names/IDs: `docker compose generate my_container`.

at least one container must be specified

Error message

at least one container must be specified

What it means

The experimental `docker compose generate` command requires at least one existing container as input to derive a Compose file from. runGenerate checks len(containers) == 0 immediately after printing its experimental warning and refuses to continue.

Source

Thrown at cmd/compose/generate.go:61

		Short: "EXPERIMENTAL - Generate a Compose file from existing containers",
		PreRunE: Adapt(func(ctx context.Context, args []string) error {
			return nil
		}),
		RunE: Adapt(func(ctx context.Context, args []string) error {
			return runGenerate(ctx, dockerCli, backendOptions, opts, args)
		}),
	}

	cmd.Flags().StringVar(&opts.ProjectName, "name", "", "Project name to set in the Compose file")
	cmd.Flags().StringVar(&opts.ProjectDir, "project-dir", "", "Directory to use for the project")
	cmd.Flags().StringVar(&opts.Format, "format", "yaml", "Format the output. Values: [yaml | json]")
	return cmd
}

func runGenerate(ctx context.Context, dockerCli command.Cli, backendOptions *BackendOptions, opts generateOptions, containers []string) error {
	_, _ = fmt.Fprintln(os.Stderr, "generate command is EXPERIMENTAL")
	if len(containers) == 0 {
		return fmt.Errorf("at least one container must be specified")
	}

	backend, err := compose.NewComposeService(dockerCli, backendOptions.Options...)
	if err != nil {
		return err
	}
	project, err := backend.Generate(ctx, api.GenerateOptions{
		Containers:  containers,
		ProjectName: opts.ProjectName,
	})
	if err != nil {
		return err
	}

	var content []byte
	switch opts.Format {
	case "json":
		content, err = project.MarshalJSON()

View on GitHub (pinned to ddc4b044b6)

Solutions

Pass one or more running container names/IDs: `docker compose generate my_container`.
Start the containers first (`docker compose up -d`) then run generate against them.
In scripts, check the container list is non-empty before invoking generate.

Example fix

# before
docker compose generate

# after
docker start my_container && docker compose generate my_container

Defensive patterns

Strategy: validation

Validate before calling

# bash
[ "$#" -ge 1 ] || { echo "usage: compose generate CONTAINER [CONTAINER...]" >&2; exit 2; }
docker compose generate "$@"

Prevention

Check `docker ps` output is non-empty before generating from containers.
Remember generate is experimental — pin behavior with tests when you adopt it.

When it happens

Trigger: Running plain `docker compose generate` with no container IDs/names as positional arguments, or passing an empty string as the only argument which cobra may treat as zero valid args.

Common situations: Trying to generate a compose file from a stopped project's containers that were already removed; misunderstanding the command as 'generate from an image or from nothing'; empty `$(docker ps -q)` expansion in scripts.

Related errors

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