{"record":{"id":"d24134b9d0070a9e","repo":"docker/cli","slug":"invalid-utf8-bytes-at-line-d-v","errorCode":null,"errorMessage":"invalid utf8 bytes at line %d: %v","messagePattern":"invalid utf8 bytes at line (.+?): (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/kvfile/kvfile.go","lineNumber":88,"sourceCode":"\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}\n\tfor currentLine := 1; scanner.Scan(); currentLine++ {\n\t\tscannedBytes := scanner.Bytes()\n\t\tif !utf8.Valid(scannedBytes) {\n\t\t\treturn []string{}, fmt.Errorf(\"invalid utf8 bytes at line %d: %v\", currentLine, scannedBytes)\n\t\t}\n\t\t// We trim UTF8 BOM\n\t\tif currentLine == 1 {\n\t\t\tscannedBytes = bytes.TrimPrefix(scannedBytes, utf8bom)\n\t\t}\n\t\t// trim the line from all leading whitespace first. trailing whitespace\n\t\t// is part of the value, and is kept unmodified.\n\t\tline := strings.TrimLeftFunc(string(scannedBytes), unicode.IsSpace)\n\n\t\tif len(line) == 0 || line[0] == '#' {\n\t\t\t// skip empty lines and comments (lines starting with '#')\n\t\t\tcontinue\n\t\t}\n\n\t\tkey, _, hasValue := strings.Cut(line, \"=\")\n\t\tif len(key) == 0 {\n\t\t\treturn []string{}, fmt.Errorf(\"no variable name on line '%s'\", line)\n\t\t}","sourceCodeStart":70,"sourceCodeEnd":106,"githubUrl":"https://github.com/docker/cli/blob/4f84911bfe8811e9b028e4b1fee8e7510be79387/pkg/kvfile/kvfile.go#L70-L106","documentation":"Returned inside parseKeyValueFile when bufio.Scanner.Bytes() for a line is not valid UTF-8. kvfile requires the whole file to be UTF-8 (a leading BOM is stripped on line 1, but any other invalid byte sequence fails). The line number and the raw bytes are included.","triggerScenarios":"An --env-file / --label-file (or compose env_file) saved in UTF-16/UTF-32, latin-1, Windows-1252, or containing a binary blob. A mid-file BOM also triggers it (only the line-1 BOM is stripped).","commonSituations":"Windows editors saving as 'Unicode' (UTF-16 LE), PowerShell Out-File defaulting to UTF-16, copy-pasting from a rich-text source introducing non-UTF-8 bytes, or committing a binary file as an env file.","solutions":["Re-encode the file to UTF-8 without BOM: 'iconv -f UTF-16 -t UTF-8 file.env > out.env' or 'dos2unix file.env'.","Remove any mid-file BOM/zero-width characters.","Validate with 'file --mime-encoding file.env' (expect utf-8) before passing it to Docker."],"exampleFix":"# before: PowerShell wrote UTF-16\n# after\nGet-Content file.env | Set-Content -Encoding utf8 file.env\n# or on unix:\niconv -f UTF-16 -t UTF-8 file.env > file.utf8.env","handlingStrategy":"validation","validationCode":"// Verify a file is UTF-8 (and strip/flag a BOM) before passing to kvfile.Parse.\nimport (\"bytes\"; \"os\"; \"unicode/utf8\")\n\nfunc isUTF8File(name string) (bool, error) {\n    b, err := os.ReadFile(name)\n    if err != nil { return false, err }\n    b = bytes.TrimPrefix(b, []byte{0xEF, 0xBB, 0xBF}) // tolerate a leading BOM\n    return utf8.Valid(b), nil\n}\n\n// ok, _ := isUTF8File(file); if !ok { return fmt.Errorf(\"%s is not valid UTF-8\", file) }","typeGuard":null,"tryCatchPattern":"if _, err := kvfile.Parse(file, lookup); err != nil {\n    return err // invalid env file (<file>): invalid utf8 bytes at line N: ...\n}","preventionTips":["Save env files as UTF-8 without BOM (avoid PowerShell's UTF-16 default).","Run 'file --mime-encoding <file>' expecting 'utf-8' in CI.","Run 'iconv -f UTF-16 -t UTF-8' / 'dos2unix' on files from Windows."],"tags":["docker","env-file","kvfile","utf8","encoding","cli"],"backgroundTag":null,"analyzedSha":"4f84911bfe8811e9b028e4b1fee8e7510be79387","analyzedAt":"2026-08-07T12:15:29.814Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}