pdf-raster

Errors and troubleshooting

Handle PdfToImagesError codes and fix the most common failures.

convert() rejects with a PdfToImagesError. Its code property is one of eight fixed strings, so you can branch on it instead of parsing messages.

Handle errors

import { convert, PdfToImagesError } from "pdf-raster";

try {
  const pages = await convert(bytes, { dpi: 300 });
} catch (error) {
  if (error instanceof PdfToImagesError) {
    console.error(error.code, error.message);
  }
  throw error;
}

Map codes to HTTP status

If you expose conversion through an API, the code tells you whose fault the failure is.

CodeCauseStatus
INVALID_INPUTThe caller sent no PDF or the wrong type.400
INVALID_OPTIONSA bad option, or a page over maxPixels.400
INVALID_PAGE_INDEXA page that does not exist.400
INVALID_CROPA crop outside the page.400
PASSWORD_ERRORMissing or wrong password.400 or 401
MALFORMED_PDFThe upload is not a readable PDF.422
PDFIUM_UNAVAILABLEYour server cannot load the native library.500
RENDER_ERRORPDFium or the encoder failed.500

Log the full message on the server, and return only the code and a short message to untrusted clients.

Common problems

Running out of memory

pdf-raster holds at most 8 rendered pages in memory at once, about 270 MB at 300 DPI on letter paper. Encoded output adds to that, and it stays in memory until you release the returned buffers. When you convert long documents, ask for pages in batches with pages and write or upload each batch before requesting the next. See Concurrency and memory.

On this page