What causes "failed to remove the CID file: %w" in docker/cli?

Ensure the directory containing the CID file remains writable for the duration of create/run.

failed to remove the CID file

Error message

failed to remove the CID file: %w

What it means

Returned by cidFile.Close() when, on close, the container ID was never written (cid.written==false) and os.Remove(cid.path) fails for a reason other than os.ErrNotExist (cli/command/container/create.go:179-181). The CID file is created up front by newCIDFile and removed if creation is aborted before an ID is written; a remove failure (e.g. permission lost, parent directory changed) is reported here.

Solutions

Ensure the directory containing the CID file remains writable for the duration of create/run.
Avoid pointing --cidfile at a path managed by another process.
Manually remove the leftover CID file and retry if a previous failed run left one (note newCIDFile itself errors if the file already exists).
Drop --cidfile if you do not need the container ID persisted to disk.

Example fix

# before
docker create --cidfile /readonly/cid myimage   # cleanup unlink denied
# after
docker create --cidfile /tmp/cid myimage

Defensive patterns

Strategy: try-catch

Try / catch

if err := cidFile.Close(); err != nil {
    // non-fatal: container creation may still be OK; log and clean up manually
}

Prevention

Point --cidfile at a stable, writable directory for the whole run.
Avoid paths owned/managed by other processes.
Treat CID-file cleanup failure as a warning; the container itself may be fine.

When it happens

Trigger: Using --cidfile <path> on docker create/run, the container creation aborts before Write(id) is called, and cleaning up the empty CID file fails. This surfaces during the deferred Close() at the end of createContainer.

Common situations: Permissions on the file/path changed between creation and cleanup (e.g. a parent dir made read-only), the file was concurrently removed and re-created by another process in a way that defeats ErrNotExist handling, or SELinux/AppArmor denies the unlink.

Related errors

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

Appendix: source

Thrown at cli/command/container/create.go:180

}

type cidFile struct {
	path    string
	file    *os.File
	written bool
}

func (cid *cidFile) Close() error {
	if cid.file == nil {
		return nil
	}
	_ = cid.file.Close()

	if cid.written {
		return nil
	}
	if err := os.Remove(cid.path); err != nil && !errors.Is(err, os.ErrNotExist) {
		return fmt.Errorf("failed to remove the CID file: %w", err)
	}

	return nil
}

func (cid *cidFile) Write(id string) error {
	if cid.file == nil {
		return nil
	}
	if _, err := cid.file.WriteString(id); err != nil {
		return fmt.Errorf("failed to write the container ID (%s) to file: %w", id, err)
	}
	cid.written = true
	return nil
}

func newCIDFile(cidPath string) (*cidFile, error) {
	if cidPath == "" {

View on GitHub (pinned to 4f84911bfe)