docker/cli · warning

cowardly refusing to save to a terminal. Use the -o flag or…

Error message

cowardly refusing to save to a terminal. Use the -o flag or redirect

What it means

Returned by `docker export` / `docker container export` when no -o/--output flag is given AND stdout is detected to be a terminal (export.go:50-53). Writing a raw tar archive to a terminal would dump binary garbage and corrupt terminal state, so the CLI refuses. The check uses dockerCLI.Out().IsTerminal().

Solutions

1. Add the -o flag: `docker export -o out.tar <container>`.
2. Redirect stdout to a file: `docker export <container> > out.tar`.
3. Pipe into another consumer so stdout is not a terminal: `docker export <container> | tar -tv`.

Example fix

// before
docker export mycontainer
// after
docker export -o mycontainer.tar mycontainer

// In a wrapper, detect a terminal and force an output path.
if out.IsTerminal() && opts.output == "" {
    return errors.New("refusing binary output to terminal; pass -o or redirect")
}

When it happens

Trigger: Running `docker export <container>` interactively in a shell without redirecting stdout or specifying -o. The combination of opts.output == "" and IsTerminal()==true triggers it.

Common situations: Forgetting the -o flag or a `> file.tar` redirect when testing export interactively; copy-pasting an export command that previously ran inside a pipe/script into a live terminal.

Related errors

• flag --use-api-socket can't be used with a Windows Docker…
• exec ID empty
• --pid: invalid PID mode
• --uts: invalid UTS mode
• --userns: invalid USER mode

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

Appendix: source

Thrown at cli/command/container/export.go:52

		Annotations: map[string]string{
			"aliases": "docker container export, docker export",
		},
		ValidArgsFunction:     completion.ContainerNames(dockerCLI, true),
		DisableFlagsInUseLine: true,
	}

	flags := cmd.Flags()

	flags.StringVarP(&opts.output, "output", "o", "", "Write to a file, instead of STDOUT")

	return cmd
}

func runExport(ctx context.Context, dockerCLI command.Cli, opts exportOptions) error {
	var output io.Writer
	if opts.output == "" {
		if dockerCLI.Out().IsTerminal() {
			return errors.New("cowardly refusing to save to a terminal. Use the -o flag or redirect")
		}
		output = dockerCLI.Out()
	} else {
		writer, err := atomicwriter.New(opts.output, 0o600)
		if err != nil {
			return fmt.Errorf("failed to export container: %w", err)
		}
		defer writer.Close()
		output = writer
	}

	responseBody, err := dockerCLI.Client().ContainerExport(ctx, opts.container, client.ContainerExportOptions{})
	if err != nil {
		return err
	}
	defer responseBody.Close()

	_, err = io.Copy(output, responseBody)

View on GitHub (pinned to 4f84911bfe)