Reference
Error Handling
Error patterns, common issues, and recovery strategies.
Error Handling
Detector not found
Calling validate() with an unregistered detector raises a KeyError:
from fastpii import FastPII, DEFAULT_PRIORITY
from fastpii.countries.cz import CzechPack
engine = FastPII(priority=DEFAULT_PRIORITY)
engine.register(CzechPack())
try:
result = engine.validate("some_value", "unknown_detector")
except KeyError as e:
print(f"Detector not found: {e}")
print(f"Available detectors: {[d.name for d in engine.list_detectors()]}")Validation failures
Validation failures do not raise exceptions. Instead, is_valid returns False:
result = engine.validate("0000000000", "rodne_cislo")
print(result.is_valid)
# False
print(result.metadata)
# {"checksum_valid": False, ...}CLI errors
Missing regions flag
fastpii detect "some text"
# Error: the following arguments are required: --regions/-rUnknown detector
fastpii validate "value" --detector unknown_detector -r cz
# Error: Detector 'unknown_detector' not found
# Available detectors: rodne_cislo, ico, dic, ...File not found
fastpii detect --file nonexistent.txt -r cz
# Error: File not found: nonexistent.txtOverlap resolution edge cases
When multiple detectors match overlapping spans, FastPII resolves conflicts using the priority dict. If no priority is provided, construction raises a ValueError:
from fastpii import FastPII
engine = FastPII()
# ValueError: Overlap priority is required. Pass a dict mapping detector type
# names to integer priorities.Always provide a priority dict:
from fastpii import FastPII, DEFAULT_PRIORITY
engine = FastPII(priority=DEFAULT_PRIORITY)Country pack registration
Country packs must be registered before their detectors can be used:
engine = FastPII(priority=DEFAULT_PRIORITY)
# No packs registered yet
result = engine.validate("8001011238", "rodne_cislo")
# KeyError: Detector 'rodne_cislo' not found
engine.register(CzechPack())
result = engine.validate("8001011238", "rodne_cislo")
# Now worksData module validation
Empty data modules return False from validate():
from fastpii.data.registry import CountryRegistry
de_module = CountryRegistry.get("de")
results = de_module.validate_all()
# {'bank_codes': False, 'names': False, 'surnames': False, ...}
# These return False because DE data modules for these types are empty stubsCheck data availability before relying on data modules for regions with partial data.