EC
UnicodeTranslateError
PythonERRORNotableValue ErrorHIGH confidence

Unicode translation failed

Production Risk

Rare; typically only in custom codec implementations.

What this means

A subclass of UnicodeError raised when a character cannot be translated during a str.translate() operation.

Why it happens
  1. 1str.translate() with a mapping that does not cover all characters in the string
  2. 2Translation table maps to None (delete) but the character is outside Latin-1
How to reproduce

str.translate() with an incomplete translation table.

trigger — this will error
trigger — this will error
s = "café"  # café
# Translation table only covering ASCII
table = str.maketrans('aeiou', '12345')
print(s.translate(table))  # May raise UnicodeTranslateError

expected output

café  → no error in this case; error occurs with custom encoders

Fix

Handle unmapped characters in the translation table

WHEN Translating strings with non-ASCII characters

Handle unmapped characters in the translation table
# Use a dict-based translation table with None for deletion
# and handle unmapped chars with the ignore or replace error handler
s = "café"
# Delete vowels including accented variants
table = str.maketrans('aeiouáéíóúàèìòùâêîôûäëïöü', '')
result = s.translate(table)

Why this works

Mapping characters to None in str.maketrans deletes them; unmapped characters pass through unchanged.

Code examples
Triggerpython
# Custom codec may raise UnicodeTranslateError
text = "héllo"
# translate with incomplete table may raise
Handle with errors parampython
result = text.encode("ascii", errors="replace").decode("ascii")
Avoid with complete translation tablepython
table = str.maketrans("aeiouáéíóú", "aeiouaeiou")
result = text.translate(table)  # all chars covered
Same error in other languages
TextDecoder errorin javascript→
Sources
Official documentation ↗

Python Docs — Built-in Exceptions

Content generated with AI assistance and reviewed for accuracy. Found an error? hello@errcodes.dev

← All Python errors