Laravel Queue PDF Timeout: Fix Dompdf Stalling with Images

How Did We Encounter the Laravel Queue PDF Timeout Issue?

While working on a recent enterprise modernization project for a global logistics SaaS platform, we encountered a puzzling infrastructure challenge. The system is responsible for generating complex daily shipping manifests—documents that include large HTML tables with dozens of rows, each paired with high-resolution product and barcode images. To ensure a smooth user experience, these heavy document-generation tasks are offloaded to background jobs via Laravel’s robust queueing system.

During a major stack upgrade from Laravel 6 (PHP 7.4) to Laravel 12 (PHP 8.3), we realized that our queue workers were suddenly stalling. A PDF generation script using Dompdf, which seamlessly pulled 18 units of data and local filesystem images, executed perfectly from the command line interface (CLI) in roughly 1.5 minutes with minimal memory overhead (under 30MB). However, the moment that exact same script was dispatched to a Laravel queue worker, the job would silently hang and ultimately trigger a timeout exception.

In a production environment processing thousands of daily shipments, a blocking queue job is catastrophic. It creates a backlog that delays critical logistics workflows. This challenge—debugging the disparity between interactive CLI execution and daemonized queue workers—inspired this article so other engineering teams can avoid the same operational bottleneck.

What Was the Business Use Case and Where Did the Dompdf Issue Appear?

The core business requirement was to automate the generation of compliance reports and shipment manifests without blocking the HTTP request cycle. The architecture relied on a standard queue-driven API layer where a controller pushes a reporting job onto a Redis-backed queue. The background worker processes the job, queries the database for the required rows, fetches the corresponding images, compiles an HTML view, and passes it to Dompdf for final rendering into a downloadable file.

While testing with smaller datasets (up to 9 rows), the legacy setup worked flawlessly. The issue surfaced exclusively under moderate load (18+ rows) inside the automated queue. Because the exact identical script ran smoothly via the terminal, it became evident that the root cause was not inherent to the script’s logic, but rather how the background execution environment interacted with network protocols, file handling, or underlying system paths in the newer Ubuntu 24.04 and PHP 8.3 environment.

What Went Wrong When Generating PDFs with Images in Background Workers?

Our initial investigation revealed no obvious application-level exceptions. The Laravel queue logs simply indicated that the job had exceeded its execution limit. To stabilize the workers, we increased the job timeout to 900 seconds and the queue retry_after to 1800 seconds. We also verified that PHP’s OPcache was enabled with an expanded opcache.memory_consumption=512 as per Dompdf’s documentation. None of these configurations resolved the hang.

When investigating further, we opted to test a modern alternative: Spatie’s Browsershot, which utilizes a headless Chrome instance via Puppeteer. While Browsershot proved faster at rendering the template, we immediately hit a wall when it ran inside the queue. The Laravel logs threw a fatal process exception:

[Production Log] ERROR: The command "PATH=$PATH:/usr/local/bin:/opt/homebrew/bin NODE_PATH=`npm root -g` "node" 'vendor/spatie/browsershot/src/../bin/browser.cjs' ... Exit Code: 127(Command not found)
Error Output:
sh: 1: npm: not found
sh: 1: node: not found

Additionally, Browsershot failed to honor specific CSS styles (like @media print constraints) and omitted page numbers. We were left with two broken paths: Dompdf was trapped in a silent stall, and Browsershot was crashing due to missing dependencies.

How Did We Approach Diagnosing the Laravel Queue Worker Stalling?

When resolving complex backend anomalies, it is critical to step back and evaluate the environmental differences. A command-line script runs under the user’s interactive session, inheriting all shell environment variables, user permissions, and network resolutions. A background queue worker, typically managed by Supervisord or Systemd, runs in a restricted daemon context.

Did We Try Increasing Queue Timeouts and Memory Limits?

Our first approach was mitigating resource exhaustion. We assumed that generating an 18-row PDF with images simply needed more time and memory in the newer, stricter PHP 8.3 worker environment. We allocated more RAM and extended timeouts. However, this approach failed because it addressed a symptom rather than the root cause. A job that takes 90 seconds in the CLI should not take 15 minutes in a queue. It wasn’t a resource issue; it was a blocking I/O issue.

Could Switching to Browsershot Solve the PDF Generation Issue?

We integrated Browsershot to bypass PHP-based rendering entirely. However, the daemonized queue environment did not have Node.js or NPM in its system $PATH. While a developer’s terminal knows exactly where Node is located, Supervisor does not load the user’s .bashrc or .zshrc. Thus, Browsershot failed with an Exit Code 127. Additionally, the headless browser struggled with our legacy print stylesheets, requiring a massive CSS refactor that we wanted to avoid.

Was Image Asset Resolution the Root Cause of the Dompdf Stall?

We hypothesized that Dompdf was blocking synchronously while trying to resolve image paths. When Dompdf encounters an image tag (<img src="https://...">), it uses PHP’s file_get_contents or cURL to download it. In a local CLI, HTTP loopbacks (the server making a request to itself) might resolve instantly via local DNS caching. However, inside a daemonized worker, SSL context verification in PHP 8.3 or DNS loopback constraints can cause the network request to hang until the socket times out. By fetching 18 images, the script suffered consecutive silent network timeouts, stalling the entire worker.

How Did We Implement the Final Fix for Laravel Queued PDF Generation?

We deployed a dual-pronged solution: one that solved the Dompdf stalling by eliminating network I/O, and one that correctly configured Browsershot for future-proofing. Ultimately, we continued with Dompdf by modifying how the HTML template consumed images.

Step 1: Eliminating Network Requests in Dompdf

Instead of passing absolute URLs to the view, we pre-processed the images into Base64 strings using the local file system. This completely bypassed the HTTP networking layer, ensuring the background worker never waited for a loopback request.

// Instead of passing URLs:
// $imageUrl = asset('storage/products/' . $product->image);
// We implemented a local asset resolver:
$imagePath = storage_path('app/public/products/' . $product->image);
if (file_exists($imagePath)) {
    $mime = mime_content_type($imagePath);
    $data = base64_encode(file_get_contents($imagePath));
    $base64Image = 'data:' . $mime . ';base64,' . $data;
}
// In the Blade template:
// <img src="{{ $base64Image }}" alt="Product Image">

This simple architectural shift reduced queue generation time back to CLI standards (under 90 seconds) and completely eliminated the stalling issue.

Step 2: Fixing Browsershot Context Limitations

To fix the Browsershot implementation for other modern reporting modules, we explicitly defined the Node and NPM paths in our implementation, bypassing the daemon’s restricted $PATH variable. We also forced the CSS print media type.

use SpatieBrowsershotBrowsershot;
Browsershot::html($htmlContent)
    ->setNodeBinary('/usr/local/bin/node')
    ->setNpmBinary('/usr/local/bin/npm')
    ->emulateMedia('screen') // Solves the print CSS rendering issues
    ->showBackground()
    ->save($pdfOutputPath);

By defining explicit paths, we guaranteed the Laravel worker could execute the headless browser regardless of the system daemon’s configuration.

What Are the Core Lessons for Engineering Teams Handling PDF Queues?

• Environment Context Matters: Never assume a command that works in the interactive CLI will work out-of-the-box in Supervisor or Systemd. Background daemons run with minimal environment variables.
• Avoid Network Loopbacks in Workers: When rendering PDFs or compiling assets, always use local filesystem paths or base64 encoding instead of HTTP URLs. Synchronous network blocking is the leading cause of queue timeouts.
• Specify Explicit Binaries: When interacting with external CLI tools (like Node, NPM, or FFmpeg) from within PHP, define absolute paths to the binaries to prevent Command not found errors.
• Monitor Upgrades Carefully: Upgrading to strict environments (like PHP 8.3) often exposes sloppy handling of SSL contexts or garbage collection that older, more forgiving versions ignored.
• Hire Software Developer Talent with Full-Stack Awareness: Resolving infrastructure issues requires an understanding of process isolation, not just framework syntax. If you intend to hire php developers for scalable backend systems, ensure they understand server environments.

How Can This Help Your Team and How to Wrap Up?

Modernizing legacy applications often uncovers hidden technical debt, particularly when background processing relies on synchronous file or network operations. By moving away from URL-based image rendering to local base64 encoding, and by explicitly defining system binary paths for modern headless rendering tools, our team stabilized the logistics platform’s entire reporting pipeline.

Whether you need to hire python developers for scalable data systems to feed your reporting engines, or you want to hire ai developers for production deployment to automate data extraction, building robust architectures is key. Similarly, organizations frequently hire dotnet developers for enterprise modernization to tackle these exact types of infrastructure bottlenecks. If you are struggling with unpredictable application performance or need dedicated engineering expertise, contact us to explore how our pre-vetted tech talent can elevate your operations.

Social Hashtags

#Laravel #Laravel12 #PHP #PHP83 #Dompdf #LaravelQueue #PDFGeneration #WebDevelopment #BackendDevelopment #SoftwareEngineering #DevOps #Browsershot #Puppeteer #Redis #PerformanceOptimization