{"record":{"id":"28bb048b285e2eb4","repo":"docker/cli","slug":"invalid-env-file-s-v","errorCode":null,"errorMessage":"invalid env file (%s): %v","messagePattern":"invalid env file \\((.+?)\\): (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/kvfile/kvfile.go","lineNumber":66,"sourceCode":"\t\"os\"\n\t\"strings\"\n\t\"unicode\"\n\t\"unicode/utf8\"\n)\n\n// Parse parses a line-delimited key/value pairs separated by equal sign.\n// It accepts a lookupFn to lookup default values for keys that do not define\n// a value. An error is produced if parsing failed, the content contains invalid\n// UTF-8 characters, or a key contains whitespaces.\nfunc Parse(filename string, lookupFn func(key string) (value string, found bool)) ([]string, error) {\n\tfh, err := os.Open(filename)\n\tif err != nil {\n\t\treturn []string{}, err\n\t}\n\tout, err := parseKeyValueFile(fh, lookupFn)\n\t_ = fh.Close()\n\tif err != nil {\n\t\treturn []string{}, fmt.Errorf(\"invalid env file (%s): %v\", filename, err)\n\t}\n\treturn out, nil\n}\n\n// ParseFromReader parses a line-delimited key/value pairs separated by equal sign.\n// It accepts a lookupFn to lookup default values for keys that do not define\n// a value. An error is produced if parsing failed, the content contains invalid\n// UTF-8 characters, or a key contains whitespaces.\nfunc ParseFromReader(r io.Reader, lookupFn func(key string) (value string, found bool)) ([]string, error) {\n\treturn parseKeyValueFile(r, lookupFn)\n}\n\nconst whiteSpaces = \" \\t\"\n\nfunc parseKeyValueFile(r io.Reader, lookupFn func(string) (string, bool)) ([]string, error) {\n\tlines := []string{}\n\tscanner := bufio.NewScanner(r)\n\tutf8bom := []byte{0xEF, 0xBB, 0xBF}","sourceCodeStart":48,"sourceCodeEnd":84,"githubUrl":"https://github.com/docker/cli/blob/4f84911bfe8811e9b028e4b1fee8e7510be79387/pkg/kvfile/kvfile.go#L48-L84","documentation":"Returned by kvfile.Parse as a wrapper ('invalid env file (<filename>): <cause>') over any error produced while scanning an env/label file (invalid UTF-8, a line with no variable name, a key containing whitespace, or the bufio scanner error). The filename is interpolated so the offending file is identifiable; the underlying cause is in %v.","triggerScenarios":"'docker run --env-file broken.env ...' where broken.env has a non-UTF-8 byte, a line like '=value' (no key), or 'MY VAR=x' (whitespace in key). Also via --label-file, or compose env_file: that routes through kvfile.Parse.","commonSituations":"Env file saved in latin-1/UTF-16/Windows-1252, an editor inserting a BOM mid-file or smart-quotes, a stray space before '=' ('VAR =x'), or a line accidentally starting with '='. The wrapped message hides which line; open the file named in the message.","solutions":["Read the wrapped cause in the error: it names the exact problem (UTF-8 line N, whitespace key, etc.).","Re-save the file as UTF-8 (no BOM) in your editor.","Fix the offending line: ensure 'KEY=value' with no spaces in KEY and a non-empty key.","If using compose, point env_file at the corrected file and re-run."],"exampleFix":"# before (broken.env, saved as UTF-16)\n# after: re-encode as UTF-8\niconv -f UTF-16 -t UTF-8 broken.env > fixed.env\ndocker run --env-file fixed.env ...","handlingStrategy":"validation","validationCode":"// Pre-flight: file must be readable AND valid UTF-8 before kvfile.Parse.\nimport (\"io\"; \"os\"; \"unicode/utf8\")\n\nfunc envFileLooksValid(name string) error {\n    f, err := os.Open(name)\n    if err != nil { return err }\n    defer f.Close()\n    buf := make([]byte, 64*1024)\n    for {\n        n, err := f.Read(buf)\n        if !utf8.Valid(buf[:n]) { return fmt.Errorf(\"%s: invalid UTF-8\", name) }\n        if err == io.EOF { break }\n        if err != nil { return err }\n    }\n    return nil\n}\n\n// if err := envFileLooksValid(file); err != nil { return err }","typeGuard":null,"tryCatchPattern":"lines, err := kvfile.Parse(file, nil)\nif err != nil {\n    // err already wraps the cause: invalid env file (<file>): <cause>\n    return fmt.Errorf(\"cannot load env file %q: %w\", file, err)\n}","preventionTips":["Always check the wrapped cause in the error to find the exact line problem.","Lint env files in CI (UTF-8, KEY=value, no spaces in keys).","Keep env files ASCII or UTF-8 without BOM."],"tags":["docker","env-file","kvfile","encoding","parsing","cli"],"backgroundTag":null,"analyzedSha":"4f84911bfe8811e9b028e4b1fee8e7510be79387","analyzedAt":"2026-08-07T12:15:29.814Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}