{"record":{"id":"8a060cb455298920","repo":"docker/cli","slug":"got-an-irregular-file","errorCode":null,"errorMessage":"got an irregular file","messagePattern":"got an irregular file","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cli/command/utils.go","lineNumber":94,"sourceCode":"\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 {\n\treturn invalidParameterErr{err}\n}\n\ntype invalidParameterErr struct{ error }\n\nfunc (invalidParameterErr) InvalidParameter() {}\n\nfunc notFound(err error) error {\n\treturn notFoundErr{err}\n}\n\ntype notFoundErr struct{ error }\n","sourceCodeStart":76,"sourceCodeEnd":112,"githubUrl":"https://github.com/docker/cli/blob/4f84911bfe8811e9b028e4b1fee8e7510be79387/cli/command/utils.go#L76-L112","documentation":"Returned by ValidateOutputPathFileMode in the docker CLI command package when validating a destination path for 'docker cp'. An irregular file is one whose os.FileMode has the ModeIrregular bit set, meaning the OS reported a file that is neither a regular file, directory, nor a device. The function refuses such paths because 'docker cp' can only copy to/from regular files or directories. It is the last guard before the copy engine touches the destination.","triggerScenarios":"Calling 'docker cp <container>:<src> /path' (or 'docker cp /path <container>:<dst>') where the destination path already exists and resolves to a FIFO/socket, or a file on a filesystem (e.g. some FUSE/overlay mounts) that reports ModeIrregular. ValidateOutputPath (utils.go:62) stats the path and, if it exists and is not a dir/regular file, delegates to ValidateOutputPathFileMode which returns this error at line 94.","commonSituations":"Copying to a named pipe, socket, or special file created in the destination directory. Filesystems that surface files as irregular (some network/NFS/FUSE drivers). A broken or partial extraction left a sentinel file. Symlink chains resolving to a non-regular target.","solutions":["Point the destination at a directory or a path that does not exist yet (docker cp will create the file).","Remove or rename the existing irregular file at the destination path, then retry the cp.","If the path is on a FUSE/network mount, retry against a local filesystem (ext4/xfs) to confirm the FS is reporting the mode.","Check for accidentally created FIFOs/sockets (e.g. leftover from 'mkfifo') in the target directory and clean them up."],"exampleFix":"// before\ndocker cp mycontainer:/app/logs.out ./logs.out   # ./logs.out is a FIFO\n\n// after\nrm ./logs.out\ndocker cp mycontainer:/app/logs.out ./logs.out   # now a regular file is created","handlingStrategy":"validation","validationCode":"// Validate a docker-cp destination before invoking the copy.\nfunc validateCpDest(path string) error {\n    fi, err := os.Stat(path)\n    if os.IsNotExist(err) {\n        return nil // absent destination is fine; docker will create it\n    }\n    if err != nil {\n        return err\n    }\n    if fi.Mode().IsDir() || fi.Mode().IsRegular() {\n        return nil\n    }\n    if fi.Mode()&os.ModeIrregular != 0 || fi.Mode()&os.ModeDevice != 0 {\n        return fmt.Errorf(\"destination %s is not a regular file or directory\", path)\n    }\n    return nil\n}","typeGuard":"// isCopyableDest reports whether a path is a valid docker-cp destination.\nfunc isCopyableDest(path string) bool {\n    fi, err := os.Stat(path)\n    if os.IsNotExist(err) {\n        return true\n    }\n    if err != nil {\n        return false\n    }\n    return fi.Mode().IsDir() || fi.Mode().IsRegular()\n}","tryCatchPattern":null,"preventionTips":["Before 'docker cp', stat the destination and reject non-regular files.","Never reuse paths that may be FIFOs/sockets as copy destinations; use a dedicated output directory.","In automation, copy to a fresh temp dir then move into place to avoid pre-existing irregular files.","If running on FUSE/network mounts, validate the destination on a local FS first."],"tags":["docker-cp","filesystem","validation","file-mode"],"backgroundTag":null,"analyzedSha":"4f84911bfe8811e9b028e4b1fee8e7510be79387","analyzedAt":"2026-08-07T12:15:29.814Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}