docker/cli · error

got a device

Error message

got a device

What it means

Thrown by ValidateOutputPathFileMode (cli/command/utils.go:92) when the destination path of a `docker cp` resolves to a device file (os.ModeDevice bit set — block or character device). Copying onto a device is unsafe and meaningless, so output-path validation rejects it before any transfer.

Solutions

1. Use a regular file or directory as the destination.
2. If a special file is ultimately intended, copy to a normal path first then redirect/write separately.
3. Stat the destination before copying and reject non-regular, non-directory targets.

Example fix

// before
docker cp web:/etc/nginx/nginx.conf /dev/sda1

// after
docker cp web:/etc/nginx/nginx.conf ./nginx.conf

// Reject device destinations before docker cp.
fi, err := os.Stat(dest)
if err == nil {
	if fi.Mode()&os.ModeDevice != 0 {
		return fmt.Errorf("destination %q is a device file", dest)
	}
}

func isRegularOrDir(fm os.FileMode) bool {
	return fm.IsRegular() || fm.IsDir()
}

When it happens

Trigger: Running `docker cp <container>:/file /dev/sda1` or targeting any path under /dev that is a device node as the copy destination.

Common situations: Destination path accidentally resolves to /dev/something; a symlink resolves to a device; operator mis-types a path that lands on a device node.

Related errors

• source can not be empty
• destination can not be empty
• must specify at least one container source
• invalid device cgroup format
• bad mode specified

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

Appendix: source

Thrown at cli/command/utils.go:92

		}

		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 {
	return invalidParameterErr{err}
}

type invalidParameterErr struct{ error }

func (invalidParameterErr) InvalidParameter() {}

func notFound(err error) error {
	return notFoundErr{err}
}

View on GitHub (pinned to 4f84911bfe)