Unstructured-IO / Unstructured-IO/unstructured

detect_filetype()/partition() raise UnicodeDecodeError on non-UTF-8 text files that start with "{" or "["

Open
#4,446 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
HTML
Stars
15.5k
Forks
1.3k
Avg merge
4d 2h
Merged PRs (30d)
13

Description

Describe the bug

A plain-text file that is not UTF-8 encoded (e.g. cp1252/latin-1) and whose first non-whitespace character is { or [ — a log file with [timestamp] lines, an INI-style [section] config — crashes file-type detection with UnicodeDecodeError instead of being classified as TXT. The crash surfaces from partition(), partition(file=...), and detect_filetype() directly.

To Reproduce

import io
from unstructured.partition.auto import partition

payload = "[2026-08-19] München report\n".encode("cp1252")
partition(file=io.BytesIO(payload))
UnicodeDecodeError: 'utf-8' codec can't decode byte 0xfc in position 14: invalid start byte

Same with a .txt file path. Requires libmagic installed (the standard setup, including the official docker image) so the file routes through the text differentiator; on environments where libmagic reports JSON files as text/plain (noted in a code comment in filetype.py), actual JSON files in legacy encodings crash the same way.

Expected behavior

The file should be classified (as TXT here) and partitioned; a content-sniffing predicate should never raise on arbitrary text input.

Root cause

_TextFileDifferentiator._is_json (unstructured/file_utils/filetype.py) runs json.load(file) on the raw byte stream and catches only json.JSONDecodeError. json.load auto-detects only UTF-8/16/32 (the JSON interchange encodings, RFC 8259), so any other charset raises UnicodeDecodeError, which escapes. The 4096-char text_head gate decodes with fallback charset detection, so it happily passes non-UTF-8 text through to the raw-bytes parse. This is a regression of #705 (fixed by #707 in 0.7.3): the old _is_text_file_a_json worked on the decoded text head.

Environment

unstructured 0.26.3 (current main, 104b585), Python 3.11, libmagic via python-magic.

I have a fix ready and will open a PR.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start in unstructured/file_utils/filetype.py at _TextFileDifferentiator._is_json, then trace the partition() and detect_filetype() entry points described in the report. Reproduce the cp1252 payload with partition(file=...) and verify that non-UTF-8 text beginning with { or [ is classified as TXT without raising.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
backend
Issue type
Bug
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.