Stirling-Tools/Stirling-PDF · error · Error

jobStatus.error

Error message

jobStatus.error

What it means

Thrown during job polling when jobStatus.complete is true AND jobStatus.error is truthy. The server-side conversion job finished but reported a failure. The error message is the server-provided jobStatus.error string, re-thrown as a new Error. This surfaces server-side conversion failures (corrupt PDF, LibreOffice crash, out of memory) to the client.

Source

Thrown at frontend/editor/src/core/tools/pdfTextEditor/PdfTextEditor.tsx:772

                Math.max(jobStatus.progress ?? 0, 0),
                100,
              );
              const stage = jobStatus.stage || "processing";
              const message = jobStatus.note || "Converting PDF to JSON...";
              const current = jobStatus.current ?? undefined;
              const total = jobStatus.total ?? undefined;
              setConversionProgress({
                percent,
                stage,
                message,
                current,
                total,
              });

              if (jobStatus.complete) {
                if (jobStatus.error) {
                  console.error("Job failed:", jobStatus.error);
                  throw new Error(jobStatus.error);
                }

                console.log("Job completed, retrieving JSON result...");
                jobComplete = true;

                const resultResponse = await apiClient.get(
                  `/api/v1/general/job/${jobId}/result`,
                  {
                    responseType: "blob",
                  },
                );

                const jsonText = await resultResponse.data.text();
                const result = JSON.parse(jsonText);

                if (!Array.isArray(result.pages)) {
                  console.error(
                    "Conversion result missing page array:",

View on GitHub (pinned to 9ef20dcab8)

Solutions

1. Read the jobStatus.error message for the specific server-side failure reason.
2. Validate the PDF is not password-protected before sending to the text editor conversion.
3. Retry with a smaller or simplified version of the document.
4. Check server logs for the underlying conversion exception (LibreOffice, PDFBox stack trace).

Example fix

// before
if (jobStatus.error) {
  console.error("Job failed:", jobStatus.error);
  throw new Error(jobStatus.error);
}

// after
if (jobStatus.error) {
  console.error("Job failed:", jobStatus.error);
  throw new Error(
    `Conversion failed: ${jobStatus.error}. The PDF may be corrupted or use unsupported features.`
  );
}

// Before submitting, validate the PDF is not encrypted
if (await isPdfEncrypted(file)) {
  setErrorMessage('This PDF is password-protected. Please unlock it first.');
  return;
}

function isJobError(status: unknown): status is { complete: true; error: string } {
  return typeof status === 'object' && status !== null &&
    (status as any).complete === true && typeof (status as any).error === 'string';
}

try {
  // ... polling loop ...
  if (jobStatus.complete && jobStatus.error) {
    throw new Error(`Conversion failed: ${jobStatus.error}`);
  }
} catch (error) {
  setErrorMessage(
    error instanceof Error && error.message.includes('Conversion failed')
      ? error.message
      : 'An unexpected error occurred during conversion.'
  );
}

When it happens

Trigger: The uploaded PDF is corrupted, encrypted, or uses features the conversion pipeline cannot handle. The server's LibreOffice/PDFBox processing threw an exception. Server ran out of memory during conversion of a large document.

Common situations: Corrupt or malformed PDF structure. Password-protected PDF sent without credentials. Server resource exhaustion under concurrent load. LibreOffice conversion timeout for complex documents.

Related errors

• Conversion timed out
• No job ID received from server
• PDF conversion result did not include page data. Please upda
• Conversion did not return JSON content
• Failed to parse PDF JSON document

AI-assisted analysis of Stirling-Tools/Stirling-PDF@9ef20dcab8 (2026-08-13). Data as JSON: /api/errors/507377b728b409d5. Report an issue: GitHub.