Stirling-Tools/Stirling-PDF · error · Error

Conversion timed out

Error message

Conversion timed out

What it means

Thrown after the polling loop exits (attempts >= maxAttempts, which is 600) without jobComplete becoming true. The job was still running or stuck when the client gave up. With exponential backoff up to 10s per poll and 600 attempts, this represents approximately 30+ minutes of polling before timeout.

Source

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

                : undefined;
              console.error("Poll error details:", {
                status,
                data: isAxiosError(pollError)
                  ? pollError.response?.data
                  : undefined,
                message:
                  pollError instanceof Error ? pollError.message : undefined,
              });
              if (status === 404) {
                throw new Error("Job not found on server", {
                  cause: pollError,
                });
              }
            }
          }

          if (!jobComplete) {
            throw new Error("Conversion timed out");
          }
          if (!parsed) {
            throw new Error("Conversion did not return JSON content");
          }
        } else {
          const content = await file.text();
          const docResult = JSON.parse(content) as PdfJsonDocument;
          parsed = {
            ...docResult,
            pages: docResult.pages ?? [],
          };
          shouldUseLazyMode = false;
          pendingJobId = null;
        }

        setConversionProgress(null);

        if (loadRequestIdRef.current !== requestId) {

View on GitHub (pinned to 9ef20dcab8)

Solutions

1. Check server resource usage (CPU, memory) during conversion — the job may be legitimately slow.
2. Try a smaller or simpler PDF to rule out document-specific issues.
3. Increase maxAttempts or make it configurable for enterprise deployments.
4. Check server logs for the job — it may still be processing after the client gave up.

Example fix

// before
if (!jobComplete) {
  throw new Error("Conversion timed out");
}

// after
if (!jobComplete) {
  throw new Error(
    `Conversion timed out after ${attempts} polling attempts. ` +
    `The server may be overloaded or the document too large. Try again or use a smaller file.`
  );
}

// Check document size and warn about potential timeout
if (file.size > 50 * 1024 * 1024) {
  // 50MB+
  setConversionProgress({ percent: 0, stage: 'processing', message: 'Large document — conversion may take several minutes.' });
}

try {
  parsed = await convertWithPolling(file, requestId);
} catch (error) {
  if (error instanceof Error && error.message === 'Conversion timed out') {
    // Retry once with fresh job
    parsed = await convertWithPolling(file, requestId);
  } else {
    throw error;
  }
}

When it happens

Trigger: The server-side conversion is genuinely stuck (deadlock, infinite loop in LibreOffice). The server is under extreme load and processing is extremely slow. Network issues causing poll responses to be received but job status never advancing.

Common situations: Very large or complex PDF with hundreds of pages. Server running on minimal resources (low CPU/RAM). LibreOffice hung on a specific problematic document. Concurrent conversions saturating the server.

Understand the failure class

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• jobStatus.error
• 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/f45deb195f7e33d4. Report an issue: GitHub.