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.
| Code | Cause | Status |
|---|---|---|
INVALID_INPUT | The caller sent no PDF or the wrong type. | 400 |
INVALID_OPTIONS | A bad option, or a page over maxPixels. | 400 |
INVALID_PAGE_INDEX | A page that does not exist. | 400 |
INVALID_CROP | A crop outside the page. | 400 |
PASSWORD_ERROR | Missing or wrong password. | 400 or 401 |
MALFORMED_PDF | The upload is not a readable PDF. | 422 |
PDFIUM_UNAVAILABLE | Your server cannot load the native library. | 500 |
RENDER_ERROR | PDFium 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.