invalid output path: must be a directory or a regular file

Error message

invalid output path: %q must be a directory or a regular file: %w

What it means

Returned by ValidateOutputPath when the destination exists and is neither a directory nor a regular file, and ValidateOutputPathFileMode rejects it (utils.go:80-82). The wrapped error is one of "got a device" or "got an irregular file" from ValidateOutputPathFileMode (utils.go:89-96). Docker cp can only target real files or directories, so device nodes, sockets, FIFOs, and irregular files are refused.

Solutions

Point the destination at a normal file path or directory instead of a device node.
If you only want to discard output, redirect the stream in your shell rather than naming /dev/null as the cp destination.
Remove or recreate the irregular file target as a regular file.

Example fix

// before
docker cp mycontainer:/logs/app.log /dev/null
// after (redirect to discard instead of using /dev/null as the file arg)
docker cp mycontainer:/logs/app.log - > /dev/null

Defensive patterns

Strategy: validation

Validate before calling

// Reject device/irregular destinations before ValidateOutputPath.
func isAcceptableOutputTarget(path string) bool {
    info, err := os.Stat(path)
    if os.IsNotExist(err) {
        return true // new file is fine
    }
    if err != nil {
        return false
    }
    return info.Mode().IsDir() || info.Mode().IsRegular()
}
// if !isAcceptableOutputTarget(dest) { return errors.New("destination must be a regular file or dir") }

Prevention

Never point docker cp output at /dev/null or other device nodes; redirect the stream instead.
If you need to discard, use `docker cp <src> -` and pipe to /dev/null at the shell level.
Validate target file modes in a helper so device/irregular files are rejected with a clearer message.

When it happens

Trigger: Calling ValidateOutputPath against a path that resolves to a device node (e.g. /dev/null, /dev/sda1) or an irregular file. Reached at utils.go:71-82 when os.Stat succeeds, the mode is not IsDir and not IsRegular, and ValidateOutputPathFileMode returns non-nil.

Common situations: Redirecting docker cp output to /dev/null or another device node; a path that is actually a named pipe or socket the user created; platform/filesystem oddities producing ModeIrregular.

Related errors

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

Appendix: source

Thrown at cli/command/utils.go:81

	dir := filepath.Dir(filepath.Clean(path))
	if dir != "" && dir != "." {
		if _, err := os.Stat(dir); os.IsNotExist(err) {
			return fmt.Errorf("invalid output path: directory %q does not exist", dir)
		}
	}
	// check whether `path` points to a regular file
	// (if the path exists and doesn't point to a directory)
	if fileInfo, err := os.Stat(path); !os.IsNotExist(err) {
		if err != nil {
			return err
		}

		if fileInfo.Mode().IsDir() || fileInfo.Mode().IsRegular() {
			return nil
		}

		if err := ValidateOutputPathFileMode(fileInfo.Mode()); err != nil {
			return fmt.Errorf("invalid output path: %q must be a directory or a regular file: %w", path, err)
		}
	}
	return nil
}

// ValidateOutputPathFileMode validates the output paths of the "docker cp" command
// and serves as a helper to [ValidateOutputPath]
func ValidateOutputPathFileMode(fileMode os.FileMode) error {
	switch {
	case fileMode&os.ModeDevice != 0:
		return errors.New("got a device")
	case fileMode&os.ModeIrregular != 0:
		return errors.New("got an irregular file")
	}
	return nil
}

func invalidParameter(err error) error {

View on GitHub (pinned to 4f84911bfe)