Troubleshooting Wkhtmltopdf Errno::EPIPE (Broken pipe) Error

Introduction

This guide will help you fix the Errno::EPIPE (Broken pipe) or wkhtmltopdf: cannot connect to X server error that occurs when using PDF exports in Easy8. This issue usually affects features like invoicing, cost estimation (calculation), and template exports when running on a headless server (no graphical environment).

Target Audience

• Administrator

Prerequisites

• Root access to the Easy8 server
• A terminal or SSH connection to the server
• The system is running on a headless Linux distribution (e.g., Debian/Ubuntu without GUI)

How to Fix the Wkhtmltopdf Broken Pipe Error

Step 1: Understand the Problem

The error message may appear like:

Errno::EPIPE (Broken pipe)
wkhtmltopdf: cannot connect to X server

This happens because:

• The version of wkhtmltopdf installed via apt-get (e.g., 0.9.9) requires a graphical environment.
• On a headless server, this causes PDF generation to fail.

Step 2: Install xvfb for Virtual X Server

sudo apt-get install xvfb

This installs a virtual frame buffer, which simulates a display and allows wkhtmltopdf to run.

Step 3: Download and Install a Suitable wkhtmltopdf Version

wget https://bitbucket.org/wkhtmltopdf/wkhtmltopdf/downloads/wkhtmltox-0.13.0-alpha-7b36694_linux-jessie-amd64.deb
sudo dpkg -i wkhtmltox-0.13.0-alpha-7b36694_linux-jessie-amd64.deb
sudo apt-get -f install

Step 4: Replace the Default Binary

sudo mv /usr/local/bin/wkhtmltopdf /usr/local/bin/xwkhtmltopdf

Step 5: Create a Wrapper Script Using xvfb-run

echo 'exec xvfb-run -a -s "-screen 0 640x480x16" xwkhtmltopdf "$@"' | sudo tee /usr/local/bin/wkhtmltopdf > /dev/null
sudo chmod a+x /usr/local/bin/wkhtmltopdf

Step 6: Test the Export Functionality

Go back to Easy8 and test PDF exports (e.g., invoice, cost calculation, or template export). The issue should be resolved.

Conclusion

You have successfully fixed the Broken pipe or X server error when exporting PDFs in Easy8. By installing a compatible version of wkhtmltopdf and running it in a virtual display environment with xvfb, PDF exports now work properly on headless servers.

Related Topics and Further Reading

• Easy8 Documentation
• wkhtmltopdf Official Downloads
• Contact Easy8 Support