Skip to main content

tool_failed

HTTP 500 · code: "tool_failed" · type: https://docs.formfeed.dev/errors/tool-failed

A PDF step failed inside Formfeed, on a source that could be read: the password protection, another PDF tool, or the PDF/UA-1 validation of a render with pdf.ua. This is Formfeed's failure, not your request's. Nothing was charged.

A source that cannot be read at all answers source_invalid, and an encrypted one source_encrypted.

Example​

{
  "type": "https://docs.formfeed.dev/errors/tool-failed",
  "title": "PDF tool failed",
  "status": 500,
  "detail": "qpdf failed (2): …",
  "code": "tool_failed",
  "location": null,
  "request_id": "req_4b7c1e9a2f3d4c5b8a6e7f9012"
}

Common causes​

  • The program that encrypts PDFs (/pdf/protect, post.password) failed on the document.
  • An unexpected failure while a PDF tool processed the document, for example a PDF structure the tools can open but not copy.
  • The validator could not read the file of a render with pdf.ua (The PDF could not be validated against PDF/UA-1, with the validator's reason).
  • A temporary failure while processing.

How to fix it​

  • Retry once with the same Idempotency-Key. If it fails again, render the source again and use the new render id.
  • If it keeps happening, send the request_id to support@formfeed.dev.

Retry?​

Once. A temporary failure goes away on a retry with the same Idempotency-Key (answers of 500 are not stored under the key); a document that triggers it fails again. Async renders with a post step are retried by the queue, and end as worker_exhausted when every attempt fails.