docker/compose · error

--index requires one service to be selected

Error message

--index requires one service to be selected

What it means

docker compose logs --index N selects one specific replica of a service by ordinal, which is only meaningful when exactly one service is named. The PreRunE in cmd/compose/logs.go rejects the combination when opts.index > 0 and the number of positional SERVICE arguments is not exactly 1 (zero or 2+ services).

Source

Thrown at cmd/compose/logs.go:57

	until      string
	noColor    bool
	noPrefix   bool
	timestamps bool
}

func logsCommand(p *ProjectOptions, dockerCli command.Cli, backendOptions *BackendOptions) *cobra.Command {
	opts := logsOptions{
		ProjectOptions: p,
	}
	logsCmd := &cobra.Command{
		Use:   "logs [OPTIONS] [SERVICE...]",
		Short: "View output from containers",
		RunE: Adapt(func(ctx context.Context, args []string) error {
			return runLogs(ctx, dockerCli, backendOptions, opts, args)
		}),
		PreRunE: func(cmd *cobra.Command, args []string) error {
			if opts.index > 0 && len(args) != 1 {
				return errors.New("--index requires one service to be selected")
			}
			return nil
		},
		ValidArgsFunction: completeServiceNames(dockerCli, p),
	}
	flags := logsCmd.Flags()
	flags.BoolVarP(&opts.follow, "follow", "f", false, "Follow log output")
	flags.SetAnnotation("follow", annotation.ExternalURL, []string{"https://docs.docker.com/reference/cli/docker/container/logs/#follow"}) //nolint:errcheck
	flags.IntVar(&opts.index, "index", 0, "index of the container if service has multiple replicas")
	flags.StringVar(&opts.since, "since", "", "Show logs since timestamp (e.g. 2013-01-02T13:23:37Z) or relative (e.g. 42m for 42 minutes)")
	flags.SetAnnotation("since", annotation.ExternalURL, []string{"https://docs.docker.com/reference/cli/docker/container/logs/#since"}) //nolint:errcheck
	flags.StringVar(&opts.until, "until", "", "Show logs before a timestamp (e.g. 2013-01-02T13:23:37Z) or relative (e.g. 42m for 42 minutes)")
	flags.SetAnnotation("until", annotation.ExternalURL, []string{"https://docs.docker.com/reference/cli/docker/container/logs/#until"}) //nolint:errcheck
	flags.BoolVar(&opts.noColor, "no-color", false, "Produce monochrome output")
	flags.BoolVar(&opts.noPrefix, "no-log-prefix", false, "Don't print prefix in logs")
	flags.BoolVarP(&opts.timestamps, "timestamps", "t", false, "Show timestamps")
	flags.SetAnnotation("timestamps", annotation.ExternalURL, []string{"https://docs.docker.com/reference/cli/docker/container/logs/#timestamps"}) //nolint:errcheck
	flags.StringVarP(&opts.tail, "tail", "n", "all", "Number of lines to show from the end of the logs for each container")

View on GitHub (pinned to ddc4b044b6)

Solutions

1. Name exactly one service when using --index: `docker compose logs --index 2 web`.
2. Drop --index if you want logs from all services or all replicas.
3. For a single-replica service, plain `docker compose logs web` is sufficient.

Example fix

# before
docker compose logs --index 1 web db

# after
docker compose logs --index 1 web

# exactly one SERVICE argument when INDEX > 0
if [ "$INDEX" -gt 0 ] 2>/dev/null && [ "$#" -ne 1 ]; then
  echo "--index requires exactly one SERVICE argument" >&2
  exit 1
fi
docker compose logs --index "$INDEX" "$@"

When it happens

Trigger: `docker compose logs --index 2` with no service argument, or `docker compose logs --index 1 web db` with two services. Note --index 0 (the default) never triggers the error because the guard requires index > 0.

Common situations: Scripts that always pass --index assuming it applies to a previously selected service; scaling a service with --scale and then inspecting logs while forgetting to name the service; copy-pasting a command template that appends multiple service names.

Related errors

• cannot combine --attach and --attach-dependencies
• unsupported --progress value %q
• unsupported format %q
• invalid --pull option %q
• invalid --scale option %q. Should be SERVICE=NUM

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