docker/cli · error

container ID file found, make sure the other container…

Error message

container ID file found, make sure the other container isn't running or delete ${cidPath}

What it means

newCIDFile (cli/command/container/create.go:197) handles the --cidfile option. At line 201-202, if os.Stat(cidPath) succeeds (the file already exists), it returns errors.New("container ID file found, make sure the other container isn't running or delete " + cidPath). The CID file mechanism writes the new container's ID to a file; a pre-existing file suggests a prior container created with that same --cidfile may still be alive, so creation is refused to avoid ambiguity.

Solutions

1. Verify whether the prior container is still needed: `docker ps -a` and check its ID against the file's contents.
2. If the old container is stale, remove it and delete the file: `docker rm <id>; rm <cidfile>`.
3. If it's safe, just delete the CID file: `rm <cidfile>`.
4. Use unique CID file paths per run (e.g. mktemp) in automation to avoid collisions.

Example fix

# before — leftover file blocks creation
docker create --cidfile ./web.cid nginx
# after — confirm nothing uses it, then remove
# cat ./web.cid  # check; docker ps -a --filter id=$(cat ./web.cid)
rm -f ./web.cid
docker create --cidfile ./web.cid nginx

// Before create, check the CID file and clean up if safe:
if cidPath != "" {
    if _, err := os.Stat(cidPath); err == nil {
        // confirm no live container uses it, then remove
        _ = os.Remove(cidPath)
    }
}

if _, err := createContainer(ctx, cli, cfg, opts); err != nil {
    if strings.Contains(err.Error(), "container ID file found") {
        // inspect prior container, remove if stale, delete the CID file, then retry
    }
    return err
}

When it happens

Trigger: Running `docker create --cidfile /path/to/id <image>` when /path/to/id already exists on disk. Triggered by re-running a create command that previously wrote the file without cleanup, or by a leftover file from a still-running container.

Common situations: Re-running a script after a partial failure that left the CID file; the previous container still running; static CID file paths in automation; container created with --cidfile then not removed.

Related errors

• source can not be empty
• destination can not be empty
• must specify at least one container source
• destination " : " must be a directory or a regular file
• failed to remove the CID file

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

Appendix: source

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

}

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 == "" {
		return &cidFile{}, nil
	}
	if _, err := os.Stat(cidPath); err == nil {
		return nil, errors.New("container ID file found, make sure the other container isn't running or delete " + cidPath)
	}

	f, err := os.Create(cidPath)
	if err != nil {
		return nil, fmt.Errorf("failed to create the container ID file: %w", err)
	}

	return &cidFile{path: cidPath, file: f}, nil
}

//nolint:gocyclo
func createContainer(ctx context.Context, dockerCLI command.Cli, containerCfg *containerConfig, options *createOptions) (containerID string, _ error) {
	config := containerCfg.Config
	hostConfig := containerCfg.HostConfig
	networkingConfig := containerCfg.NetworkingConfig

	var namedRef reference.Named

View on GitHub (pinned to 4f84911bfe)