conflicting options: cannot specify both --attach and…

Error message

conflicting options: cannot specify both --attach and --detach

What it means

Returned by runContainer when --detach is set but copts.attach still has entries (--attach / -a). Attaching to streams is meaningless when detached, so the CLI rejects the combination before creating the container. The guard is at run.go:132-135 inside the detach branch.

Solutions

Choose one: drop --attach to run detached, or drop --detach to attach.
Use -d alone for background containers; the daemon streams are not consumed by your terminal.
If you need logs from a detached container, use `docker logs` afterward.

Example fix

// before
docker run -d --attach STDOUT alpine

// after
docker run -d alpine

Defensive patterns

Strategy: validation

Validate before calling

if detach && len(attachStreams) > 0 {
    return errors.New("conflicting options: cannot specify both --attach and --detach")
}

Prevention

Decide run mode upfront: attached (interactive) vs detached (backgrounded).
In scripts, make --attach and --detach mutually exclusive via your flag builder.
Use `docker logs` for detached container output instead of --attach.

When it happens

Trigger: `docker run -d --attach STDOUT alpine` or `docker run --detach --attach STDIN ...`. detach is true and copts.attach.Len() != 0.

Common situations: Migrating an attached-run command to backgrounded and forgetting to remove --attach. Aliases/scripts that always add -a. Confusion between --attach (stream attach) and -i/-a for interactive.

Related errors

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

Appendix: source

Thrown at cli/command/container/run.go:134

	}
	return runContainer(ctx, dockerCLI, ropts, copts, containerCfg)
}

//nolint:gocyclo
func runContainer(ctx context.Context, dockerCli command.Cli, runOpts *runOptions, copts *containerOptions, containerCfg *containerConfig) error {
	config := containerCfg.Config
	stdout, stderr := dockerCli.Out(), dockerCli.Err()
	apiClient := dockerCli.Client()

	config.ArgsEscaped = false

	if !runOpts.detach {
		if err := dockerCli.In().CheckTty(config.AttachStdin, config.Tty); err != nil {
			return err
		}
	} else {
		if copts.attach.Len() != 0 {
			return errors.New("conflicting options: cannot specify both --attach and --detach")
		}

		config.AttachStdin = false
		config.AttachStdout = false
		config.AttachStderr = false
		config.StdinOnce = false
	}

	detachKeys := runOpts.detachKeys
	if detachKeys == "" {
		detachKeys = dockerCli.ConfigFile().DetachKeys
	}
	if err := validateDetachKeys(runOpts.detachKeys); err != nil {
		return err
	}

	containerID, err := createContainer(ctx, dockerCli, containerCfg, &runOpts.createOptions)
	if err != nil {

View on GitHub (pinned to 4f84911bfe)