Technology · PRACTICAL GUIDE
ElementTree says “unbound prefix”? Prove the namespace before repairing the XML
Preserve the original bytes, distinguish a broken document from a detached fragment, and inject a namespace only when an authoritative URI proves the binding.
ElementTree raises “unbound prefix” when a qualified name uses a prefix that has no namespace declaration in scope. The same message can describe a malformed full document or a valid fragment detached from an ancestor that supplied the binding. Preserve the original bytes before deciding which case you have.
Do not guess the URI and do not treat register_namespace() as a parser fix. Prove the binding from an authoritative full document, schema, producer contract, or captured ancestor; if proven, inject it only into an in-memory wrapper and verify expanded names, attributes, text, tail content, and the exact repair manifest.
Preserve the evidence before repair
Read and hash the original bytes before decoding or editing. Record the parser, Python version, error line and column, and every prefix visible near the failure. Keep the immutable source alongside any repaired copy.
If upstream transport supplied only a fragment, capture that boundary explicitly. A fragment without its former ancestor is different evidence from a producer that emitted an invalid standalone document.
Classify scope loss before choosing a fix
Inspect the full document and ancestor chain for xmlns declarations. If the binding exists outside the fragment, recover that exact declaration from the authoritative parent or contract. If no authoritative URI exists, reject or quarantine instead of inventing one.
The same lexical prefix can map to different URIs in different scopes. Matching the spelling alone is not proof of namespace identity.
Keep parse, query, and serialization controls separate
register_namespace() affects output prefix selection; it does not make malformed input parseable. Likewise, the namespaces argument to find() maps query prefixes after a tree exists. Neither repairs an undeclared input prefix.
If an authoritative URI is proven, wrap the fragment in memory with one namespace declaration, parse that wrapper, and retain a manifest describing the added binding and source digest. Do not overwrite the received bytes.
Quarantine broad recovery
A tolerant parser may close tags, discard tokens, or alter unrelated structure while also bypassing the namespace error. Use recovery only as forensic extraction, never as silent production repair.
Compare recovery output with the immutable source and list every parser diagnostic. If the change set is broader than the single proven binding, fail acceptance.
Accept semantic identity, not parse success
Assert expected {URI}local element and attribute names, node counts, ordering where relevant, text, tail content, and application identifiers. Serialize only after those checks and compare a normalized signature appropriate to the contract.
Store the original digest, authoritative URI source, wrapper text or transformation, parser diagnostics, and acceptance results. A clean parse without this evidence does not prove the XML means the same thing.
