docker/cli · error

got an irregular file

Error message

got an irregular file

What it means

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.

Solutions

1. Point the destination at a directory or a path that does not exist yet (docker cp will create the file).
2. Remove or rename the existing irregular file at the destination path, then retry the cp.
3. If the path is on a FUSE/network mount, retry against a local filesystem (ext4/xfs) to confirm the FS is reporting the mode.
4. Check for accidentally created FIFOs/sockets (e.g. leftover from 'mkfifo') in the target directory and clean them up.

Example fix

// before
docker cp mycontainer:/app/logs.out ./logs.out   # ./logs.out is a FIFO

// after
rm ./logs.out
docker cp mycontainer:/app/logs.out ./logs.out   # now a regular file is created

// Validate a docker-cp destination before invoking the copy.
func validateCpDest(path string) error {
    fi, err := os.Stat(path)
    if os.IsNotExist(err) {
        return nil // absent destination is fine; docker will create it
    }
    if err != nil {
        return err
    }
    if fi.Mode().IsDir() || fi.Mode().IsRegular() {
        return nil
    }
    if fi.Mode()&os.ModeIrregular != 0 || fi.Mode()&os.ModeDevice != 0 {
        return fmt.Errorf("destination %s is not a regular file or directory", path)
    }
    return nil
}

// isCopyableDest reports whether a path is a valid docker-cp destination.
func isCopyableDest(path string) bool {
    fi, err := os.Stat(path)
    if os.IsNotExist(err) {
        return true
    }
    if err != nil {
        return false
    }
    return fi.Mode().IsDir() || fi.Mode().IsRegular()
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• invalid output path: directory
• invalid output path: must be a directory or a regular file
• source can not be empty
• destination can not be empty
• must specify at least one container source

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

Appendix: source

Thrown at cli/command/utils.go:94

		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}
}

type notFoundErr struct{ error }

View on GitHub (pinned to 4f84911bfe)