Troubleshooting & FAQ
If your question isn’t covered here, email support@bytera.tech.
XPress doesn’t appear in a space sidebar
Section titled “XPress doesn’t appear in a space sidebar”Possible causes:
- App not fully installed — go to Settings → Apps → Manage apps in Confluence and confirm XPress is Enabled.
- Browser cache — hard-refresh (Cmd/Ctrl + Shift + R).
- License expired — if XPress is installed but you see a “License Required” message, renew the trial or subscription from Marketplace.
Page tree is empty
Section titled “Page tree is empty”If you open XPress and the page tree shows no pages:
- The space has no published pages — create at least one page in Confluence first.
- The space is restricted in a way that hides pages from your account — XPress respects Confluence permissions and only shows pages you can already see.
My export shows “Failed”
Section titled “My export shows “Failed””Open the Exports tab and click the Failed row to see the status message. Common causes and fixes:
| Status message hint | Likely cause | Fix |
|---|---|---|
| ”Timeout” / “took too long” | Very large bulk export, possibly image-heavy | Break the selection into smaller batches and re-run |
| ”Image fetch failed” | Network hiccup pulling embedded images | Re-run the export |
| ”Unsupported content” | A page contains a macro or content type XPress couldn’t render | Re-export without the offending page; tell us what macro it was |
| ”Permission denied” | You lost access to one of the selected pages between selection and render | Refresh the page tree and re-select |
A specific page is missing from the PDF
Section titled “A specific page is missing from the PDF”- The page was selected but XPress couldn’t render it (a per-page silent failure in some edge cases). Check the page in Confluence; if it has unusual macros, try removing them and re-exporting.
- The page was added to the space after you built your selection. Selections aren’t auto-updated; deselect-and-reselect to refresh.
Images aren’t appearing / are broken
Section titled “Images aren’t appearing / are broken”XPress embeds images attached to the Confluence page directly in the PDF. Causes of missing images:
- External images — images that link to non-Atlassian URLs (e.g., a blog screenshot hosted on someone’s server) aren’t always reliably embedded. The recommended workaround is to upload images as Confluence attachments.
- Permissions — XPress reads images using the same permissions as you. If you can’t see an image in the source page, it won’t appear in the PDF.
- Image format — some unusual image formats may not embed correctly. Standard PNG and JPEG are well-tested.
Tables look squished / overflow the page
Section titled “Tables look squished / overflow the page”Wide tables (lots of columns) can overflow the PDF page if the page width isn’t sufficient.
Fixes:
- Switch the orientation to Landscape in Settings.
- If still overflowing, switch the paper size to A3.
- If specific columns are very wide, consider narrowing them in the source Confluence page.
Code blocks lose their formatting
Section titled “Code blocks lose their formatting”Code blocks in PDFs are rendered with a monospace font and the same syntax-highlighting that Confluence uses on the page. Some very long lines may wrap differently in the PDF than they do on screen.
If a code block looks wrong:
- Check that the source page renders the code block correctly.
- Consider switching the export to Landscape for wide code.
- Very long lines without spaces may not wrap; break them in the source for cleaner PDF output.
Confluence panels render but look slightly different
Section titled “Confluence panels render but look slightly different”Info/warning/note panels, status macros, and similar Confluence elements render in the PDF using the export-time HTML output. The styling is close to but not identical to what you see live in Confluence — colors and spacing match well, but some inline details may differ.
This is expected. If a panel is missing entirely (not just styled slightly differently), that’s a bug — let us know.
Bulk export is taking forever
Section titled “Bulk export is taking forever”- Image-heavy bulk exports take time. Each embedded image is fetched and embedded in the PDF.
- The per-job time limit means very large bulk exports (hundreds of pages with hundreds of images) may not finish in one job.
Fix: split the export into two or three smaller batches by selecting parts of the page tree separately.
I can’t reorder pages within a bulk export
Section titled “I can’t reorder pages within a bulk export”Page order in the PDF follows the page tree order in Confluence — top to bottom, then children below their parent. There’s no per-export reorder feature.
Workaround: temporarily reorder pages in the Confluence space, run the export, then restore the order.
Settings reset every time I open XPress
Section titled “Settings reset every time I open XPress”This is by design today — settings are session-only. Per-space saved templates are on the roadmap.
Does XPress work with Confluence Data Center / Server?
Section titled “Does XPress work with Confluence Data Center / Server?”No. XPress is a Forge app and runs only on Confluence Cloud.
How do I get more help?
Section titled “How do I get more help?”- Email: support@bytera.tech
- Feature requests: reply to any support email with
Feature request:in the subject
- Changelog — what’s new and what’s coming.