{"record":{"id":"4a842433290ead14","repo":"agentscope-ai/agentscope","slug":"failed-to-decode-filename-r-as-self-encoding-r","errorCode":null,"errorMessage":"Failed to decode {filename!r} as {self.encoding!r}: {e}","messagePattern":"Failed to decode (.+?) as (.+?): (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/agentscope/rag/_parser/_text.py","lineNumber":104,"sourceCode":"                :attr:`Section.source`.\n\n        Returns:\n            `list[Section]`:\n                Always a one-element list containing the entire file\n                contents.\n\n        Raises:\n            `ValueError`: If the bytes cannot be decoded with the\n                configured encoding.\n        \"\"\"\n        if isinstance(file, str):\n            if os.path.isfile(file):\n                with open(file, \"rb\") as fp:\n                    raw = fp.read()\n                try:\n                    text = raw.decode(self.encoding)\n                except UnicodeDecodeError as e:\n                    raise ValueError(\n                        f\"Failed to decode {filename!r} as \"\n                        f\"{self.encoding!r}: {e}\",\n                    ) from e\n            else:\n                text = file\n        else:\n            try:\n                text = file.decode(self.encoding)\n            except UnicodeDecodeError as e:\n                raise ValueError(\n                    f\"Failed to decode {filename!r} as \"\n                    f\"{self.encoding!r}: {e}\",\n                ) from e\n\n        return [\n            Section(\n                content=TextBlock(text=text),\n                source=filename,","sourceCodeStart":86,"sourceCodeEnd":122,"githubUrl":"https://github.com/agentscope-ai/agentscope/blob/e90f1c7592896cc95f6e5ee506194f533378247d/src/agentscope/rag/_parser/_text.py#L86-L122","documentation":"The text parser tried to decode file bytes using the configured encoding (default utf-8) and hit a UnicodeDecodeError. This variant occurs when the input is an existing file path on disk.","triggerScenarios":"TextParser.parse('/path/file.txt') or build_index over a file containing bytes invalid in self.encoding, e.g. Latin-1/CP1252 files with smart quotes parsed as utf-8.","commonSituations":"Windows-authored text files (CP1252), mixed-encoding corpora, or binary files with a .txt extension fed into a RAG indexing job.","solutions":["Detect and pass the correct encoding: TextParser(encoding=charset_normalizer.detect(raw)['encoding'])","Convert the file to UTF-8 once: iconv -f cp1252 -t utf-8","Use errors-tolerant preprocessing or 'latin-1' which never fails","Skip non-text files when walking directories"],"exampleFix":"# before\nparser = TextParser()  # utf-8\nparser.parse('notes.txt')\n# after\nparser = TextParser(encoding='cp1252')\nparser.parse('notes.txt')","handlingStrategy":"fallback","validationCode":"from charset_normalizer import from_path\nmatch = from_path('file.txt').best()\nenc = match.encoding if match else 'utf-8'","typeGuard":null,"tryCatchPattern":"try:\n    parser = TextParser(); parser.parse(path)\nexcept ValueError:\n    parser = TextParser(encoding='latin-1'); parser.parse(path)","preventionTips":["Detect encoding with charset_normalizer/chardet before parsing","Normalize corpus to UTF-8 at ingest time","Skip files whose detected confidence is low"],"tags":["encoding","unicode","text","rag"],"backgroundTag":"unicode-decode-error","analyzedSha":"e90f1c7592896cc95f6e5ee506194f533378247d","analyzedAt":"2026-08-28T18:24:12.087Z","schemaVersion":2},"datasetVersion":"2026-08-28T21:17:43.275Z"}