What causes "failed to create the container ID file: %w" in docker/cli?

Create the parent directory first: mkdir -p $(dirname ).

failed to create the container ID file

Error message

failed to create the container ID file: %w

What it means

Returned by newCIDFile when os.Create(cidPath) fails while setting up the CID file for --cidfile (cli/command/container/create.go:205-207). This runs before any daemon call. Common os.Create failures: parent directory missing (ENOENT), permission denied (EACCES), or an existing path component is not a directory (ENOTDIR). Note a pre-existing file at cidPath is caught earlier (line 201-203) with a distinct 'container ID file found' message.

Solutions

Create the parent directory first: mkdir -p $(dirname <path>).
Use a writable location such as /tmp or the project dir.
Fix permissions on the target directory: chmod u+w <dir>.
Ensure the path does not already exist (a pre-existing file yields a different, earlier error).

Example fix

# before
docker create --cidfile /var/run/no-such-dir/cid myimage   # parent missing
# after
mkdir -p /tmp/cids && docker create --cidfile /tmp/cids/cid myimage

Defensive patterns

Strategy: validation

Validate before calling

// Validate the --cidfile path can be created before invoking docker create.
func validateCidPath(path string) error {
    dir := filepath.Dir(path)
    if fi, err := os.Stat(dir); err != nil || !fi.IsDir() {
        return fmt.Errorf("cidfile parent dir %s missing or not a directory", dir)
    }
    if _, err := os.Stat(path); err == nil {
        return errors.New("cidfile already exists; remove it first")
    }
    // try a probe create/remove
    f, err := os.Create(path)
    if err != nil { return err }
    f.Close(); os.Remove(path)
    return nil
}

Prevention

mkdir -p the parent directory before using --cidfile.
Use an absolute, writable path under /tmp or the project dir.
Ensure the path does not already exist from a prior run.

When it happens

Trigger: Running docker create/run --cidfile <path> where the parent directory does not exist, is not writable, or the path is otherwise invalid for file creation. The error short-circuits container creation.

Common situations: Typo in path, missing parent directory, permission denied, read-only filesystem, or a path that traverses a file as if it were a directory.

Related errors

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

Appendix: source

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

	}
	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

	// TODO(thaJeztah): add a platform option-type / flag-type.
	if options.platform != "" {
		if _, err := platforms.Parse(options.platform); err != nil {
			return "", err
		}

View on GitHub (pinned to 4f84911bfe)