container ID file found, make sure the other container isn't

Error message

container ID file found, make sure the other container isn't running or delete %s

What it means

newCIDFile, used by `docker run`/`docker create` with the --cidfile flag, refuses to write the container ID if the target file already exists (os.Stat succeeds). This is a deliberate safety guard: an existing cidfile likely belongs to a still-running or previously created container, and silently overwriting it could orphan that container's tracking.

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

Solutions

Delete the stale file after confirming the previous container is stopped/removed: `rm /path/to/file.cid`.
Add cleanup to your service/script lifecycle (e.g. ExecStopPost=/bin/rm -f %t/app.cid in systemd).
Use a unique cidfile path per invocation, or check `docker ps` for a container matching the ID in the file before removing it.

Example fix

# before
docker run --cidfile /run/app.cid myimage   # fails: file exists
# after
docker rm -f "$(cat /run/app.cid)" 2>/dev/null; rm -f /run/app.cid
docker run --cidfile /run/app.cid myimage

When it happens

Trigger: `docker run --cidfile /path/to/pid.cid ...` or `docker create --cidfile ...` where the file at that path already exists — typically left over from a prior run that was not cleaned up.

Common situations: Init scripts or systemd units that use --cidfile but do not delete the file on container stop; re-running a failed script; two services accidentally configured with the same cidfile path.

Related errors

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