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

mkdir -p the parent directory first

failed to export container: %w

Error message

failed to export container: %w

What it means

The --output value given to 'docker compose export' failed command.ValidateOutputPath — the path is not usable as a write target (unreadable parent dir, path is a directory, or otherwise invalid for creating/truncating a file) and compose fails before starting the export.

Source

Thrown at pkg/compose/export.go:51

	return Run(ctx, func(ctx context.Context) error {
		return s.export(ctx, projectName, options)
	}, "export", s.events)
}

func (s *composeService) export(ctx context.Context, projectName string, options api.ExportOptions) error {
	projectName = strings.ToLower(projectName)

	container, err := s.getSpecifiedContainer(ctx, projectName, oneOffInclude, false, options.Service, options.Index)
	if err != nil {
		return err
	}

	if options.Output == "" {
		if s.stdout().IsTerminal() {
			return fmt.Errorf("output option is required when exporting to terminal")
		}
	} else if err := command.ValidateOutputPath(options.Output); err != nil {
		return fmt.Errorf("failed to export container: %w", err)
	}

	name := getCanonicalContainerName(container)
	s.events.On(api.Resource{
		ID:     name,
		Text:   api.StatusExporting,
		Status: api.Working,
	})

	responseBody, err := s.apiClient().ContainerExport(ctx, container.ID, client.ContainerExportOptions{})
	if err != nil {
		return err
	}

	defer func() {
		if err := responseBody.Close(); err != nil {
			s.events.On(errorEventf(name, "Failed to close response body: %s", err.Error()))
		}

View on GitHub (pinned to ddc4b044b6)

Solutions

mkdir -p the parent directory first
Point -o at a file path in a writable location
Ensure the path is a file, not an existing directory
Check filename validity (no stray shell characters)

Example fix

# before
docker compose export web -o /tmp/exports/fs.tar   # /tmp/exports missing
# after
mkdir -p /tmp/exports && docker compose export web -o /tmp/exports/fs.tar

Defensive patterns

Strategy: validation

Validate before calling

if err := command.ValidateOutputPath(path); err != nil {
    if mkErr := os.MkdirAll(filepath.Dir(path), 0o755); mkErr != nil { return mkErr }
    if err := command.ValidateOutputPath(path); err != nil { return err }
}

Prevention

mkdir -p parent dirs in wrappers before export
Use absolute output paths in scripts
Ensure output path isn't an existing directory

When it happens

Trigger: docker compose export web -o /nonexistent-dir/x.tar, -o pointing at an existing directory, or an unwritable location; also weird paths like empty after shell expansion.

Common situations: Output dir not created yet; typo in path; read-only mount; using a path where a directory of the same name exists.

Related errors

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