What causes "failed to export container: %w" in docker/cli?

Ensure the parent directory exists and is writable: mkdir -p $(dirname OUTFILE) && chmod u+w $(dirname OUTFILE).

failed to export container

Error message

failed to export container: %w

What it means

Returned by runExport in export.go:58 when atomicwriter.New fails to create the output file for `docker export -o <file>`. The wrapped %w is the os.OpenFile error from atomicwriter. This is a host-filesystem error, not a container-export error.

Solutions

Ensure the parent directory exists and is writable: mkdir -p $(dirname OUTFILE) && chmod u+w $(dirname OUTFILE).
Remove or avoid pointing -o at an existing directory.
Check disk space and that the filesystem is mounted read-write.
Verify the path spelling.

Example fix

# before
docker export -o /tmp/exports/box.tar box
# /tmp/exports does not exist -> error

# after
mkdir -p /tmp/exports && docker export -o /tmp/exports/box.tar box

Defensive patterns

Strategy: validation

Validate before calling

func validateExportOut(path string) error {
    dir := filepath.Dir(path)
    if info, err := os.Stat(dir); err != nil || !info.IsDir() {
        return fmt.Errorf("output directory not usable: %s", dir)
    }
    if f, err := os.OpenFile(path, os.O_WRONLY|os.O_CREATE|os.O_EXCL, 0o600); err != nil {
        return err
    } else { f.Close(); os.Remove(path); }
    return nil
}

Try / catch

if err := exportCmd.Run(); err != nil && strings.Contains(err.Error(), "failed to export container") {
    // re-check path writability rather than treating as daemon error
}

Prevention

Create the parent directory before running docker export -o.
Avoid pointing -o at an existing directory.
Ensure write permission and free disk space.

When it happens

Trigger: `docker export -o /path/to/file <container>` where /path/to/file cannot be created: the parent directory does not exist, permission denied, read-only filesystem, or the path points to an existing directory.

Common situations: Typo in the output path, missing parent directory, no write permission on the target dir, or `-o` pointing at an existing directory.

Related errors

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

Appendix: source

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

	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)
	return err
}

View on GitHub (pinned to 4f84911bfe)