Error Handling

Understand FastPII runtime errors, validation failures, and common CLI error cases.

FastPII uses a small set of straightforward error patterns.

Unknown detectors raise KeyError

Both PrivacyGuard.validate() and PrivacyGuard.detect(..., detector_names=[...]) look up detectors by name through the registry.

If a detector does not exist, a KeyError is raised.

from fastpii import PrivacyGuard

guard = PrivacyGuard(regions=["cz"])

try:
    guard.validate("12345", "unknown_detector")
except KeyError:
    print("Detector not found")

The same applies to selective detection:

from fastpii import PrivacyGuard

guard = PrivacyGuard(regions=["cz"])

try:
    guard.detect("IČO: 25596641", detector_names=["unknown_detector"])
except KeyError:
    print("Detector not found")

Invalid values return `is_valid=False`

Validation failures are returned as data instead of exceptions.

from fastpii import PrivacyGuard

guard = PrivacyGuard(regions=["cz"])
result = guard.validate("8001011235", "rodne_cislo")

print(result.is_valid)

Output:

False

CLI error messages

Missing detect input

If you run fastpii detect without text and without --file, the CLI exits with an error.

Error: Either text or --file must be provided

Unknown validator in the CLI

fastpii validate catches KeyError and prints a user-facing message.

Error: Detector 'unknown_detector' not found
Available detectors: rodne_cislo, ico, dic, bank_account, postal_code, phone, email, name, address, date_of_birth, vehicle_plate

Missing file in the CLI

Error: File not found: contract.txt

Practical pattern

For Python applications, wrap detector lookup boundaries in try/except KeyError and treat failed validation as normal control flow.

from fastpii import PrivacyGuard

guard = PrivacyGuard(regions=["cz"])

try:
    result = guard.validate("25596641", "ico")
    if result.is_valid:
        print("Valid value")
    else:
        print("Invalid value")
except KeyError:
    print("Detector configuration error")