Troubleshooting¶
Start with the first error in the report: one cause often produces several
findings, and fixing it usually clears the rest. fledge rule CODE explains any
code, and --report FILE saves the full JSON report of a blocked run.
Common findings¶
TEX005: missing dependency¶
A file named by \input, \includegraphics, \bibliography or a similar
command is not in the project. The build then fails too (build.failed,
BLD009 “File not found”). Add the file, or correct the path in the source.
Paths are case-sensitive on many submission systems, so Fig.pdf and fig.pdf
are different files (TEX007).
BLD001, BLD002, BIB101, TEX004: undefined citation or reference¶
BLD001 and BLD002 come from TeX’s log; BIB101 and TEX004 come from
Fledge’s own source scan and point at the line. Correct the misspelled key, add
the missing \label or bibliography entry, or declare the right .bib file,
then rerun. The quick start shows an example.
TEX324: ambiguous main file¶
The finding is named project.main_selection. The project contains more than one
file with \documentclass, such as a paper and its slides, and Fledge does not
guess. Pass --main main.tex, set main = "main.tex" in fledge.toml, or configure
independent packages
for several documents.
BIB102: unused bibliography entries¶
These entries are never cited. This is an advisory: Fledge never removes
entries on its own. If the entries are intentional, add \nocite{key} or ignore
the check with --ignore BIB102. To ship only cited entries, opt in to
cited_only under bibliography transformations.
While a citation error is present, BIB102 can be a side effect of it.
TEX009: generated bibliography not shipped¶
The paper uses BibTeX or Biber, but no generated main.bbl sits beside the main
file. Services that compile without running BibTeX or Biber, such as arXiv, then
show empty citations. By default this is a not-applicable note, listed only
with --show-passed, that does not change the outcome;
[submission_checks] require_bbl = true, which the arxiv preset sets, makes
it a warning. To fix it, build locally and keep the generated
main.bbl (and, for biblatex, main.run.xml) next to main.tex. prepare
ships them automatically, also with --layout flat. With BibTeX you can instead
inline the bibliography with source_transforms.inline_bibliography. A .bbl
from Biber must match the biblatex version of the compiling service.
BIB109, which the arxiv preset also enables, checks that the shipped .bbl
contains every cited key. A missing key is an error: rebuild the bibliography
after your last citation change. Without a shipped .bbl, BIB109 is
inconclusive and defers to TEX009.
BIB110 compares the format version on the second line of a shipped biblatex
.bbl with submission_checks.biblatex_bbl_format_version. biblatex rejects a
.bbl written in another format, so a mismatch is an error. Look up the TeX
Live release in the service’s current instructions, then build with that
release’s biblatex; TeX Live 2026, for example, writes format 3.3. The
arxiv preset contains this setting as a commented placeholder.
PDF104: fonts not embedded¶
A font in the PDF is not embedded; this check runs when require_embedded_fonts
is on, as in every preset. The finding names the font. Fonts missing from a
figure are fixed by re-exporting that figure with embedded fonts (in matplotlib,
for example, set pdf.fonttype to 42). For the document itself, use fonts
that pdfLaTeX embeds, such as Latin Modern via \usepackage{lmodern}.
TEX001, PRV007: TODO and private-note markers¶
TEX001 finds TODO, FIXME, XXX and ?? in the active text; PRV007 finds
private notes, such as reviewer correspondence or “do not submit”, in comments.
Both are advisories. Finish or remove the text.
source_transforms.comment_policy = "private", which the arxiv preset sets,
removes only comments that contain TODO, FIXME, XXX, private, internal,
confidential or note to self. It keeps a comment such as “Reviewer 2 wants
this shortened” or “do not submit”, so the notes PRV007 reports can remain in
the prepared copy. To drop every comment from the prepared copy, set
comment_policy = "all"; comment blocks that carry a license notice or a
formatter directive are kept either way. Otherwise, delete or rewrite the
reported comments in your sources. A deliberate marker can be accepted with a
suppression.
By symptom¶
Problem |
Next step |
|---|---|
Command not found |
With the installer, use |
Installer refuses an existing destination |
Choose a fresh |
Exit code 64 |
Invalid command-line syntax; see |
“Request error” (exit 4) |
The command cannot run as given: an unusable |
|
A defect, not a problem with your paper. Keep the command and the JSON report when reporting it, and rerun with |
Unexpected configuration |
Check |
Unknown setting or selector |
The request error suggests the closest valid name, such as |
Output already exists |
Choose a new path outside the input. |
Isolation failure or Biber preparation failure |
See installation and Biber on macOS. |
Build failed |
Read |
Missing or incomplete build trace |
Resolve the reported build evidence. Preparation cannot choose package contents safely without a complete trace. |
A wanted extra file is omitted |
List its source-relative path under |
|
A name that is not valid on every operating system was kept unchanged; rename it if the submission system rejects it. |
Time or resource limit |
Try |
Flattening or source edit blocked |
Review the unsupported path or syntax finding; use |
PDF comparison fails |
Review the differences and the preservation rules. |
Online check skipped |
The note is listed only with |
An unexplained wait, skip or tool failure |
Rerun with |
Online checks cannot connect |
Online checks connect directly and ignore proxy settings such as |
Diagnostic log¶
--debug, or FLEDGE_DEBUG=1 in the environment, makes any command print log lines
to stderr while it runs. The option is hidden from --help because it is meant for
investigating a problem or reporting one; it also prints the traceback of an internal
error. Standard output is unchanged, so --output-format json still prints only the
report and can be piped while you watch stderr.
+0.412s runtime: tool start: pdflatex -halt-on-error +1 more argument
+3.870s runtime: tool end: pdflatex -halt-on-error +1 more argument (exit 0, 3.45 s)
+0.415s scheduler: task bibliography checks: blocked by failed source checks
Each line shows the time since the process started, the module that wrote it and a message. The log covers:
every tool command: the tool, the names of its options (no values and no paths), its exit status and how long it ran. A limit (time, output or resources) that stopped the tool is marked
[info];online requests: the host, method, status and duration, and the outcome of a fetch. URLs, query strings and the contact address are never logged;
scheduled tasks: when each started and ended, how long it waited for resources and which failed prerequisite blocked it;
PDF measurements that ran a tool or reused an earlier output;
which settings file was discovered (its name, not its directory) and whether the name is a legacy
latex-prepone;when the shared source analysis was built or reused.
Lines show this machine’s home directory as ~ and its temporary directory as
<tmp>; credential-shaped text and terminal control characters are removed, and the
traceback that --debug prints for a defect gets the same treatment. Still, read the
log before sharing it. Without the option Fledge prints no log
lines at all. When you embed Fledge as a library, the latexprep logger has only a
NullHandler; attach your own handler to receive the records.
Getting help¶
Keep the exact command, the Fledge and tool versions (recorded in the JSON
report’s tools), the effective settings and the relevant findings. Add the
diagnostic log of a rerun with --debug when the problem is a
wait, a skipped check or a tool failure. Read diagnostics before sharing them;
Fledge sends nothing automatically.
