Stirling-Tools/Stirling-PDF · error · Error

PDF conversion result did not include page data. Please upda

Error message

PDF conversion result did not include page data. Please update the server.

What it means

Thrown after successful job completion and result retrieval when the JSON result does not contain a pages array (Array.isArray(result.pages) is false). The conversion pipeline is expected to return { pages: [...], ... } — a missing pages array means the server returned a different schema, indicating a version mismatch between client and server.

Source

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

                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:",
                    result,
                  );
                  throw new Error(
                    "PDF conversion result did not include page data. Please update the server.",
                  );
                }

                const docResult = result as PdfJsonDocument;
                parsed = {
                  ...docResult,
                  pages: docResult.pages ?? [],
                };
                shouldUseLazyMode = Boolean(docResult.lazyImages);
                pendingJobId = shouldUseLazyMode ? jobId : null;
                setConversionProgress(null);
              } else {
                console.log("Job not complete yet, continuing to poll...");
              }
            } catch (pollError) {
              console.error("Error polling job status:", pollError);
              const status = isAxiosError(pollError)

View on GitHub (pinned to 9ef20dcab8)

Solutions

Update the server to match the client's expected schema version.
Add backward-compatible parsing: check for alternative field names (e.g., result.data.pages, result.result.pages).
Log the full result object to diagnose the schema mismatch.
Add a version check at app startup and warn if server/client versions are incompatible.

Example fix

// before
if (!Array.isArray(result.pages)) {
  throw new Error("PDF conversion result did not include page data. Please update the server.");
}

// after
const pages = result.pages ?? result.data?.pages ?? result.result?.pages;
if (!Array.isArray(pages)) {
  console.error("Unexpected result schema:", Object.keys(result));
  throw new Error("PDF conversion result did not include page data. Please update the server.");
}

Defensive patterns

Strategy: type-guard

Validate before calling

// Validate the result schema before using it
const pages = result.pages ?? result.data?.pages ?? result.result?.pages;
if (!Array.isArray(pages)) {
  throw new Error('Conversion result schema mismatch — check server version compatibility.');
}

Type guard

function hasPagesArray(result: unknown): result is { pages: unknown[] } {
  return typeof result === 'object' && result !== null && Array.isArray((result as any).pages);
}

Try / catch

try {
  const result = JSON.parse(jsonText);
  if (!hasPagesArray(result)) {
    throw new Error('Server returned incompatible result format.');
  }
} catch (error) {
  setErrorMessage('Conversion result format is incompatible. Please update the server.');
}

Prevention

Keep client and server versions in sync — schema changes require coordinated deployment.
Add a server version check at app startup and warn on mismatch.
Support multiple result schema versions with backward-compatible parsing.
Log the full result keys when the pages array is missing to diagnose schema drift.

When it happens

Trigger: The server is running an older or newer version that produces a different JSON structure. The conversion endpoint returned a partial or error result that parsed as valid JSON but lacks the pages field. A server-side bug in the serialization pipeline.

Common situations: Client upgraded but server wasn't updated (or vice versa). Server running a forked or custom build with a different output schema. Conversion produced an empty result that was serialized without the pages key.

Related errors

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