Skip to content

troubleshooting.md

Latest commit

 

History

History
117 lines (87 loc) · 4.68 KB

troubleshooting.md

File metadata and controls

117 lines (87 loc) · 4.68 KB
Raw

Troubleshooting

Symptom-first answers to the most common GraphCompose surprises. Each entry links to the canonical doc where there is more depth.

A stray ? appears in the PDF — or rating dots / arrows / checkmarks vanish

Cause. The built-in base-14 fonts (HELVETICA, TIMES, COURIER) use WinAnsi encoding — roughly 220 characters (Latin-1 plus a few typographic extras). A code point the resolved font cannot encode is replaced with ? at render time (PdfFont.sanitizeForRender) so width measurement and emitted bytes stay in lockstep. The classic trap: the bullet • (U+2022) is in WinAnsi, but the larger black circle ● (U+25CF), → ▶ ✓ ★, and emoji are not.

Fix (pick one).

  • Draw symbols as geometry, not text — inline-shape runs (dot, arrow, chevron, diamond, star, checkmark, checkbox) render from vectors and ignore font coverage. Recommended for rating dots and status markers.
  • Register a font family that covers the glyphs you need and select it via DocumentTextStyle.fontName(...).
  • Stay inside WinAnsi (• not ●, - / – not arrows).

Full detail and the coverage table: font coverage and glyph fallback.

DOCX export is missing shapes, lines, ellipses, or barcodes

Cause. The DOCX backend (DocxSemanticBackend, Apache POI) is a semantic exporter. POI cannot express fixed-layout graphics, so shape, line, ellipse, and barcode nodes are dropped silently, and ShapeContainerNode clipping / DocumentTransform rotation + scale fall back to inline content with a one-time capability warning.

Fix. Export those documents to PDF (the full-fidelity backend). Use DOCX only for paragraph / list / table / image / section content. Per-feature mapping: canonical ↔ legacy parity matrix.

MissingBackendException when rendering

Cause. You depend on graph-compose-core (the lean 2.0 engine) but no render backend is on the classpath. The core carries the DocumentSession authoring API and a ServiceLoader seam, but the actual renderer ships separately — so document.buildPdf() / toPdfBytes() / toImages() throws MissingBackendException until a backend is discoverable.

Fix. Add the PDF backend, or depend on graph-compose (which already bundles it):

<dependency>
  <groupId>io.github.demchaav</groupId>
  <artifactId>graph-compose-render-pdf</artifactId>
  <version>2.0.0</version>
</dependency>

The exception message names the exact artifact to add. Plain graph-compose and graph-compose-bundle both include the PDF backend out of the box — only a deliberately lean graph-compose-core needs this.

NoClassDefFoundError at runtime

GraphCompose keeps the heavier office backends in separate artifacts so PDF-only consumers don't pay for them. If you use DOCX export, add the dependency to your project.

DOCX export — document.export(new DocxSemanticBackend()) ships in the graph-compose-render-docx artifact, which brings Apache POI transitively:

<dependency>
  <groupId>io.github.demchaav</groupId>
  <artifactId>graph-compose-render-docx</artifactId>
  <version>2.0.0</version>
</dependency>

The bundled examples won't resolve graph-compose

Cause. examples/ is a separate Maven module that depends on the published library artifact, not on the source tree next to it.

Fix. Install the library to your local repository once from the repo root, then run an example:

./mvnw -DskipTests install
./mvnw -f examples/pom.xml exec:java -Dexec.mainClass=com.demcha.examples.GenerateAllExamples

More: examples/README.

Building from source

Build fails copying fonts — The cloud file provider is not running. The checkout lives in a cloud-synced folder (OneDrive / Dropbox / iCloud) and the font resources under fonts/src/main/resources/fonts/ (the graph-compose-fonts module, since v1.8.0) are dehydrated placeholders. Make sure the sync client is running and the files are downloaded locally ("Always keep on this device"), or move the checkout outside the synced folder.

Windows git error — cannot update the ref 'HEAD' … Invalid argument. Same cloud-folder cause, this time affecting .git. Apply git's own suggestion:

git config windows.appendAtomically false

See CONTRIBUTING.md for the full build and test gate.

See also