Diagnostics

Every compile parses the LaTeX log into a list of diagnostics. They appear in the JSON envelope (result.diagnostics), in 422 problem bodies, and the counts in result.errors, result.warnings and the X-Compile-Warnings header.

DiagnosticCopy Anchor Link

{
  "severity": "error",
  "message": "Undefined control sequence.",
  "file": "sections/intro.tex",
  "line": 12,
  "context": "l.12 \\foo\n         bar",
  "source": "latex"
}

What is detectedCopy Anchor Link

• Engine errors in file:line: message form.
• Undefined control sequence, Missing $ inserted, File ... not found, Package X Error and Class X Error blocks.
• Overfull and underfull boxes, undefined references and citations, package warnings (LaTeX Warning, Package X Warning).
• latexmk and bibtex/biber failures.

Anything the parser does not understand stays in the raw log, which you can always download from logUrl.

Mapping to statusesCopy Anchor Link

A 422 body looks like this:

{
  "type": "https://latex-api.crafter.run/docs/errors#compile_failed",
  "title": "Compilation failed",
  "status": 422,
  "detail": "LaTeX reported 2 errors",
  "code": "compile_failed",
  "jobId": "2d2ea4f9-5a4d-4d8f-8e4d-0e7b6a7a9c31",
  "errors": 2,
  "warnings": 1,
  "diagnostics": [
    { "severity": "error", "message": "Undefined control sequence.", "file": "main.tex", "line": 7, "context": "l.7 \\foo" },
    { "severity": "error", "message": "Missing $ inserted.", "file": "main.tex", "line": 9 },
    { "severity": "warning", "message": "Overfull \\hbox (12.3pt too wide) in paragraph at lines 15--16", "file": "main.tex", "line": 15 }
  ],
  "logUrl": "https://latex-api.crafter.run/v1/jobs/2d2ea4f9-.../log",
  "pdfUrl": "https://latex-api.crafter.run/v1/jobs/2d2ea4f9-.../pdf"
}

TipsCopy Anchor Link

• Treat 422 as a normal outcome: show the diagnostics to your users with the file and line. Warnings never fail a compile.
• halt-on-error stops at the first error, so a 422 usually lists one error and the warnings before it. Fix it and compile again.
• Keep X-Job-Id (or jobId) around: the full log stays at /v1/jobs/{id}/log for 24 h.