docker/cli · error

--label-file

Error message

--label-file: %w

What it means

Returned in opts.go:515 when opts.ReadKVStrings fails while reading --label-file entries (combined with inline --label values). The wrapped %w carries the file or parse error.

Solutions

1. Verify the file exists and is readable.
2. Ensure each line is KEY=VALUE with a valid label key (dotted/segmented keys allowed, value optional).
3. Fix encoding/line endings.

Example fix

# before: labels.list contains 'com.example.role' (no =)
docker run --label-file labels.list alpine

# after: labels.list contains 'com.example.role=web'
docker run --label-file labels.list alpine

// Validate label-file lines are KEY=VALUE (value optional) before docker:
for _, p := range labelFiles {
    f, err := os.Open(p)
    if err != nil { return fmt.Errorf("label-file unreadable: %w", err) }
    defer f.Close()
    sc := bufio.NewScanner(f)
    for sc.Scan() {
        line := strings.TrimSpace(sc.Text())
        if line == "" || strings.HasPrefix(line, "#") { continue }
        if !strings.Contains(line, "=") { return fmt.Errorf("bad label line: %q", line) }
    }
}

// Deterministic file error; fix the file, do not retry.
if err != nil && strings.Contains(err.Error(), "--label-file") {
    /* surface offending file/line */
}

When it happens

Trigger: `docker run --label-file <path>` where the file is missing/unreadable or a label line is malformed (labels must be KEY=VALUE).

Common situations: Wrong path, permission denied, a line missing the `=` or with an invalid key, or encoding issues.

Related errors

• --env-file
• container ID file found, make sure the other container…
• invalid pull option: ' ': must be one of , or
• saving creds
• is not a valid mac address

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

Appendix: source

Thrown at cli/command/container/opts.go:515

			return nil, err
		}
		deviceMapping, err := parseDevice(validated, serverOS)
		if err != nil {
			return nil, err
		}
		deviceMappings = append(deviceMappings, deviceMapping)
	}

	// collect all the environment variables for the container
	envVariables, err := opts.ReadKVEnvStrings(copts.envFile.GetSlice(), copts.env.GetSlice())
	if err != nil {
		return nil, fmt.Errorf("--env-file: %w", err)
	}

	// collect all the labels for the container
	labels, err := opts.ReadKVStrings(copts.labelsFile.GetSlice(), copts.labels.GetSlice())
	if err != nil {
		return nil, fmt.Errorf("--label-file: %w", err)
	}

	pidMode := container.PidMode(copts.pidMode)
	if !pidMode.Valid() {
		return nil, errors.New("--pid: invalid PID mode")
	}

	utsMode := container.UTSMode(copts.utsMode)
	if !utsMode.Valid() {
		return nil, errors.New("--uts: invalid UTS mode")
	}

	usernsMode := container.UsernsMode(copts.usernsMode)
	if !usernsMode.Valid() {
		return nil, errors.New("--userns: invalid USER mode")
	}

	cgroupnsMode := container.CgroupnsMode(copts.cgroupnsMode)

View on GitHub (pinned to 4f84911bfe)