{"record":{"id":"0975a8579a75b135","repo":"docker/cli","slug":"env-file-w","errorCode":null,"errorMessage":"--env-file: %w","messagePattern":"--env-file: %w","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cli/command/container/opts.go","lineNumber":509,"sourceCode":"\t\tif cdi.IsQualifiedName(device) {\n\t\t\tcdiDeviceNames = append(cdiDeviceNames, device)\n\t\t\tcontinue\n\t\t}\n\t\tvalidated, err := validateDevice(device, serverOS)\n\t\tif err != nil {\n\t\t\treturn nil, err\n\t\t}\n\t\tdeviceMapping, err := parseDevice(validated, serverOS)\n\t\tif err != nil {\n\t\t\treturn nil, err\n\t\t}\n\t\tdeviceMappings = append(deviceMappings, deviceMapping)\n\t}\n\n\t// collect all the environment variables for the container\n\tenvVariables, err := opts.ReadKVEnvStrings(copts.envFile.GetSlice(), copts.env.GetSlice())\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"--env-file: %w\", err)\n\t}\n\n\t// collect all the labels for the container\n\tlabels, err := opts.ReadKVStrings(copts.labelsFile.GetSlice(), copts.labels.GetSlice())\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"--label-file: %w\", err)\n\t}\n\n\tpidMode := container.PidMode(copts.pidMode)\n\tif !pidMode.Valid() {\n\t\treturn nil, errors.New(\"--pid: invalid PID mode\")\n\t}\n\n\tutsMode := container.UTSMode(copts.utsMode)\n\tif !utsMode.Valid() {\n\t\treturn nil, errors.New(\"--uts: invalid UTS mode\")\n\t}\n","sourceCodeStart":491,"sourceCodeEnd":527,"githubUrl":"https://github.com/docker/cli/blob/4f84911bfe8811e9b028e4b1fee8e7510be79387/cli/command/container/opts.go#L491-L527","documentation":"Returned in opts.go:509 when opts.ReadKVEnvStrings fails while reading --env-file entries (combined with inline --env values). The wrapped %w is the file-read or parse error from the env-file loader.","triggerScenarios":"`docker run --env-file <path>` where the file is missing/unreadable, or contains a line that does not conform to the KEY=VALUE / KEY parsing rules, or a line is malformed.","commonSituations":"Wrong file path, permission denied reading the file, BOM/encoding issues, a line like `=VALUE` (empty key), or invalid characters in a key.","solutions":["Check the file path exists and is readable: ls -l <path>.","Ensure every line is KEY=VALUE (or KEY), with valid key characters ([A-Za-z_][A-Za-z0-9_]*).","Strip BOM/CRLF; use unix line endings.","Remove or quote problematic lines."],"exampleFix":"# before: env.list contains a line '=FOO'\ndocker run --env-file env.list alpine\n\n# after: env.list contains 'FOO=bar'\ndocker run --env-file env.list alpine","handlingStrategy":"validation","validationCode":"// Read and validate the env-file before passing it to docker:\nfor _, p := range envFiles {\n    f, err := os.Open(p)\n    if err != nil { return fmt.Errorf(\"env-file unreadable: %w\", err) }\n    defer f.Close()\n    sc := bufio.NewScanner(f)\n    for sc.Scan() {\n        line := strings.TrimSpace(sc.Text())\n        if line == \"\" || strings.HasPrefix(line, \"#\") { continue }\n        if !strings.Contains(line, \"=\") && !envKeyRe.MatchString(line) {\n            return fmt.Errorf(\"bad env line: %q\", line)\n        }\n    }\n}","typeGuard":null,"tryCatchPattern":"// File/parse errors are deterministic; fix the file rather than retry.\nif err != nil && strings.Contains(err.Error(), \"--env-file\") {\n    /* surface offending file/line */\n}","preventionTips":["Ensure KEY=VALUE on every non-comment line.\nVerify file path and read permission.\nStrip BOM/CRLF."],"tags":["container","env","filesystem","flag-validation","create"],"backgroundTag":null,"analyzedSha":"4f84911bfe8811e9b028e4b1fee8e7510be79387","analyzedAt":"2026-08-07T12:15:29.814Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}