{"record":{"id":"8eea32b8f23a50f3","repo":"docker/cli","slug":"invalid-output-path-q-must-be-a-directory-or-a-r","errorCode":null,"errorMessage":"invalid output path: %q must be a directory or a regular file: %w","messagePattern":"invalid output path: %q must be a directory or a regular file: %w","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cli/command/utils.go","lineNumber":81,"sourceCode":"\tdir := filepath.Dir(filepath.Clean(path))\n\tif dir != \"\" && dir != \".\" {\n\t\tif _, err := os.Stat(dir); os.IsNotExist(err) {\n\t\t\treturn fmt.Errorf(\"invalid output path: directory %q does not exist\", dir)\n\t\t}\n\t}\n\t// check whether `path` points to a regular file\n\t// (if the path exists and doesn't point to a directory)\n\tif fileInfo, err := os.Stat(path); !os.IsNotExist(err) {\n\t\tif err != nil {\n\t\t\treturn err\n\t\t}\n\n\t\tif fileInfo.Mode().IsDir() || fileInfo.Mode().IsRegular() {\n\t\t\treturn nil\n\t\t}\n\n\t\tif err := ValidateOutputPathFileMode(fileInfo.Mode()); err != nil {\n\t\t\treturn fmt.Errorf(\"invalid output path: %q must be a directory or a regular file: %w\", path, err)\n\t\t}\n\t}\n\treturn nil\n}\n\n// ValidateOutputPathFileMode validates the output paths of the \"docker cp\" command\n// and serves as a helper to [ValidateOutputPath]\nfunc ValidateOutputPathFileMode(fileMode os.FileMode) error {\n\tswitch {\n\tcase fileMode&os.ModeDevice != 0:\n\t\treturn errors.New(\"got a device\")\n\tcase fileMode&os.ModeIrregular != 0:\n\t\treturn errors.New(\"got an irregular file\")\n\t}\n\treturn nil\n}\n\nfunc invalidParameter(err error) error {","sourceCodeStart":63,"sourceCodeEnd":99,"githubUrl":"https://github.com/docker/cli/blob/4f84911bfe8811e9b028e4b1fee8e7510be79387/cli/command/utils.go#L63-L99","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\ndocker cp mycontainer:/logs/app.log /dev/null\n// after (redirect to discard instead of using /dev/null as the file arg)\ndocker cp mycontainer:/logs/app.log - > /dev/null","handlingStrategy":"validation","validationCode":"// Reject device/irregular destinations before ValidateOutputPath.\nfunc isAcceptableOutputTarget(path string) bool {\n    info, err := os.Stat(path)\n    if os.IsNotExist(err) {\n        return true // new file is fine\n    }\n    if err != nil {\n        return false\n    }\n    return info.Mode().IsDir() || info.Mode().IsRegular()\n}\n// if !isAcceptableOutputTarget(dest) { return errors.New(\"destination must be a regular file or dir\") }","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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."],"tags":["docker-cp","output-path","filesystem","device","validation"],"backgroundTag":null,"analyzedSha":"4f84911bfe8811e9b028e4b1fee8e7510be79387","analyzedAt":"2026-08-07T12:15:29.814Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}