How can I report text-file decoding errors without silently replacing characters?

Choose the encoding you expect the file to use, then read a limited sample with strict decoding. For example, assuming the file is expected to be UTF-8 and the path is sample.txt:

from pathlib import Path

path = Path("sample.txt")
expected_encoding = "utf-8"

try:
    with path.open("r", encoding=expected_encoding, errors="strict") as file:
        sample = file.read(2000)
except FileNotFoundError:
    print(f"File not found: {path}")
except UnicodeDecodeError:
    print(f"Could not decode sample using {expected_encoding}.")
else:
    print("Sample decoded under the expected encoding.")
    print(sample)

The exception branches mean different things: FileNotFoundError reports that the requested path does not exist, while UnicodeDecodeError reports that bytes could not be decoded using the selected encoding. [S1] UTF-8 is only an example here; set expected_encoding to the encoding your file is supposed to use.

Replacement handling inserts replacement characters where decoding fails. That is a poor first diagnostic: the resulting text no longer faithfully represents the original bytes, and substitutions can obscure where decoding failed. [S1]

For a diagnostic report, preserve the distinction between “the expected encoding decoded this sample” and “it did not.” If you later create a replacement-based preview, label it clearly as altered output and keep it separate from the original file. Do not treat that preview as evidence that the source bytes were intact.

No. It tells you that the bytes could not be decoded under the encoding you selected; it does not establish which alternative encoding, if any, is correct. [S1] Keep the error report factual: name the expected encoding and report that decoding failed rather than guessing a replacement encoding.

Check the sample’s origin or the system that produced it for an encoding declaration or documented setting. If that information is unavailable, record that the encoding remains unknown and ask the file’s provider how it was produced. There is no universal encoding-detection method established by this exception guidance. [S1]

Include enough context to reproduce the check without overstating what it proves. For example:

Sample decoding check File: [path or sample identifier] Expected encoding: [encoding] Sample read limit: [number] Result: [decoded / UnicodeDecodeError] Missing-file check: [FileNotFoundError occurred / did not occur] Encoding source: [documentation, producer setting, or unknown] Replacement handling used: No

This reports the outcome under the selected encoding; it does not prove the file’s intended encoding or the cause of a mismatch. Avoid pasting sensitive file contents into a report; a path or approved sample identifier may be enough. If you need to share file data for investigation, follow your organization’s handling rules.