*Epic CLI Manual — [index](../MANUAL.md)*

# 15. Troubleshooting and landmines

**A jar that runs but reports emptier output than expected** — missing spot colors, zeroed
thin-line data, colorspaces not found inside `/Fm` form XObjects — is the signature of a
stale or dirty-tree build, not a data problem. This exact regression shipped once (see
`CLAUDE.md`, commit `ded7016`'s history) and went undetected because the jar still ran; it
just quietly did less. Verify the jar's provenance before debugging the file.

**JDK 21 is forbidden.** `--extract-objects` output fragments ~55× under the JDK 21
`java.awt.geom.Area` regression. JDK 8/11/17/23 are clean.

**`--create=4x6` is rejected** — an argument-length guard fires before the size regex; write
the spec longer (`--create=4.00x6.00`). And `--create` is not a mode by itself — combine it
with a transform or `--imposition`.

**Exit 3 on imposition** = a `recolor` entry named a separation the placed PDF doesn't have.
The error message lists the separations the file actually contains — fix the plan, not the
file.

**Parsing stdout without checking exit codes?** Key on `"status"` — every standalone mode's
error path still emits a well-formed JSON object.

**`--vectorize` output has too many inks** → set `--max-colors` to the job's real ink count
(the single best artifact-killer), then `--delta-e` up for noisy JPEG sources.

**Hairlines vanish in `--vectorize`** → they're being smoothed or snapped away: `--smooth=0`,
rely on `--min-area`, and keep `--ink-threshold` at its default (that mechanism exists
precisely to save half-covered hairlines).

**White plate missing / white plate unwanted** → `--paper` is `none` by default because
near-white can be a real plate (underbase). Pass `--paper=auto` when the background truly is
paper.

**Illustrator private data by hand** (if you ever must):
- Never edit `%AI5_NumLayers` — Illustrator counts layers itself and hard-crashes on a
  mismatch.
- AIPDFPrivateData chunks may be individually Flate-filtered — read them decoded, never raw,
  before concatenating and zstd-decompressing (`%AI24_ZStandard_Data` header, 65536-byte
  chunks).
- Illustrator **ignores** PDF-content layer markings (`/OC` OCGs, `/Layer` BDC,
  `OCProperties`) when building its Layers panel — named layers exist only in the PieceInfo
  private data. Adding OCGs will not make AI show a layer.

**`--spool` fails silently in CI/sandboxes** — it needs a real print subsystem (Windows
spooler or CUPS) and has deliberately no retry.