Appearance
When TEI Publisher will not render your edition correctly, the cause is almost always one of four things: no Processing Model behaviour matches your elements (so they show as raw or unstyled), your document structure lacks the <div>s the navigation needs, your facsimile URLs are unreachable or blocked by CORS, or a stale cache is serving an old transform after you fixed the real problem. Work through them in that order — check the browser console first, then the ODD, then the document structure — and most "TEI Publisher is broken" reports resolve in minutes.
Why is my text showing as raw XML?
This is the single most common failure. TEI Publisher renders through a Processing Model defined in an ODD; if no model rule matches an element, it falls through and you see tags or unstyled text. Open the ODD editor, find the element, and confirm a behaviour exists:
xml
<elementSpec ident="lb" mode="change">
<model behaviour="break">
<param name="type" value="'line'"/>
</model>
</elementSpec>If the element is genuinely unhandled, add a model rule and recompile. Also verify your root <TEI> carries a valid structure; a malformed header can stop the whole binding before any rule runs.
Why is my table of contents empty?
The navigation index is built from structural divisions. TEI Publisher walks <div> elements and their @type/@n attributes to construct the ToC. A text encoded as flat <p> runs with only <milestone> markers gives it nothing to index. Either introduce real structural divs:
xml
<div type="chapter" n="1">
<head>Of the Beginning</head>
<p>...</p>
</div>or reconfigure the navigation in the ODD to recognise your milestones. Restructuring the source is the more durable fix.
How do I diagnose missing facsimile images?
Open the browser developer console and look at the network tab while loading the page. The image request will tell you the truth: a 404 means a wrong path, a 403 or a CORS message means a server policy problem. TEI Publisher is rarely at fault here.
| Console symptom | Root cause | Fix |
|---|---|---|
404 Not Found | Wrong <graphic url> or IIIF id | Correct the manifest/URL |
403 Forbidden | Image server auth/referrer | Allow the Publisher origin |
| CORS blocked | Missing Access-Control-Allow-Origin | Configure the IIIF server CORS |
| Mixed content | HTTP image on HTTPS page | Serve images over HTTPS |
Why does eXist-db run out of memory on big editions?
TEI Publisher runs on eXist-db, a JVM application with a fixed heap. Large corpora or whole-document transforms exhaust it. Raise the heap and stop transforming everything at once:
text
# in exist's launcher config or JAVA_OPTS
-Xmx4g -XX:+UseG1GCThen paginate. Render and index per document or per page rather than building the entire corpus in one request. If a single edition needs more than 4 GB to render, your Processing Model is probably doing too much per request.
Why didn't my ODD change take effect?
Because the ODD is compiled, not interpreted live, and caches sit between you and the output. After editing, you must recompile the ODD in the Publisher editor, then clear caches:
bash
# clear browser cache for the page, then in eXist:
# Dashboard > restart, or remove cached transforms under /db/appsA fix that "didn't work" has often worked perfectly and is hidden behind a stale transform. Always confirm with a hard reload before assuming the change failed.
When should I stop fighting and switch tools?
TEI Publisher earns its complexity when you need full-text search and faceting across a corpus. For a single small edition, the eXist-db maintenance, the heap tuning, and the cache hunts are pure overhead. If you find yourself troubleshooting infrastructure more than encoding, a static renderer (EVT or CETEIcean) publishes the same TEI with none of the server burden. Knowing when to walk away is itself a debugging skill.
Key Takeaways
- Raw-XML output means no Processing Model rule matches an element; fix the ODD and recompile.
- An empty ToC means your text lacks the structural
<div>s the navigation indexes. - Diagnose missing images from the browser console: distinguish 404, 403, and CORS.
- Raise the eXist-db JVM heap and paginate transforms to stop out-of-memory errors.
- Always recompile the ODD and clear caches; stale transforms mask working fixes.
- TEI Publisher suits corpus search; for one small edition, a static renderer is simpler.
- Check the console first — many "Publisher bugs" are server or URL problems.
Frequently Asked Questions
Why does my document show raw XML instead of formatted text in TEI Publisher?
Usually no ODD/Processing Model behaviour matches your elements, so they fall through unstyled. Open the ODD in the Publisher editor, confirm a model exists for the offending element, and recompile. A missing or wrong @xml:id on <TEI> can also break the binding.
My edition uploads but the table of contents is empty — what is wrong?
The navigation depends on <div> structure and @type/@n attributes. If your text uses <milestone> or flat paragraphs without divs, TEI Publisher finds no nodes to index. Add structural divs or adjust the navigation configuration in the ODD.
Why do my facsimile images not appear?
Check that your <facsimile>/<graphic> points to a reachable IIIF or image URL and that CORS allows the Publisher origin. A 403 or CORS error in the browser console is the usual culprit, not a TEI Publisher bug.
How do I fix an eXist-db out-of-memory error on large editions?
Raise the JVM heap in the launcher or exist-launcher settings (for example -Xmx4g), and avoid loading the whole corpus into one transform. Paginate the Processing Model output and index incrementally rather than rebuilding the full set each request.
Why did my changes not appear after editing the ODD?
The ODD must be recompiled and the cache cleared. In the Publisher ODD editor, save and recompile; then reload the document. Browser and eXist caches frequently serve a stale transform, masking a fix that actually worked.
Is TEI Publisher overkill for a single small edition?
Often yes. If you do not need dynamic search across a corpus, a static renderer (EVT or CETEIcean) avoids the eXist-db maintenance burden entirely. Choose TEI Publisher when querying and faceting across many documents is a real requirement.