docker/cli · error

got an irregular file

Error message

got an irregular file

What it means

Returned by ValidateOutputPathFileMode for `docker cp` when the destination's file mode has os.ModeIrregular set — a file that is neither regular, directory, symlink, device, pipe, nor socket (platform-specific irregular entries). docker cp cannot safely write archive contents onto such a target, so validation rejects it, wrapped in "invalid output path: ... must be a directory or a regular file".

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 e9452d6e78)

Solutions

1. Choose a destination on a normal filesystem that is a regular file or directory.
2. Inspect the destination with `ls -la` / `stat` to see what the path actually is, and delete or rename the irregular entry if it's stale.
3. On Windows/WSL, avoid copying onto reparse points or interop-mounted special paths.

When it happens

Trigger: `docker cp <src> <dst>` where os.Stat on the local destination reports ModeIrregular — e.g. certain Windows reparse points, some overlay/union-fs or virtual-filesystem entries — hitting cli/command/utils.go:94.

Common situations: Copying onto paths inside unusual mounts (FUSE, WSL interop paths, Windows special reparse points); destination paths generated by scripts that accidentally reference virtual filesystem entries.

Related errors

• got a device
• plugin candidate path cannot be empty
• plugin SchemaVersion version cannot be empty
• config file is required
• source can not be empty

AI-assisted analysis of docker/cli@e9452d6e78 (2026-08-01). Data as JSON: /data/errors/8a060cb455298920.json. Report an issue: GitHub.