Troubleshooting GitHub Actions: Resolving wkhtmltopdf dependency issues in a Django project
Recently, while working on an API documentation update for a Python Django project, I encountered an unexpected issue. After pushing my code to GitHub, I noticed that the GitHub Actions pipeline had failed. This was surprising because I hadn’t made any changes to the code that would affect the pipeline. Curious to find out what went wrong, I headed over to the GitHub Actions page to inspect the details of the failure.
The Initial Error Message
The error message I found indicated a problem with the installation of wkhtmltopdf, a popular tool for converting HTML to PDF. Here is the relevant portion of the log:
Selecting previously unselected package wkhtmltox.
(Reading database ... 220631 files and directories currently installed.)
Preparing to unpack wkhtmltox_0.12.6-1.bionic_amd64.deb ...
Unpacking wkhtmltox (1:0.12.6-1.bionic) ...
dpkg: dependency problems prevent configuration of wkhtmltox:
Processing triggers for man-db (2.12.0-4build2) ...
wkhtmltox depends on libssl1.1; however:
Package libssl1.1 is not installed.
dpkg: error processing package wkhtmltox (--install):
dependency problems - leaving unconfigured
Errors were encountered while processing:
wkhtmltox
Error: Process completed with exit code 1.
Investigating the Issue
From the error message, it was clear that the installation of wkhtmltox failed due to a missing dependency: libssl1.1. The package manager dpkg was unable to configure wkhtmltox because it couldn’t find libssl1.1.
My first thought was to add a step to install libssl1.1 before attempting to install wkhtmltopdf. However, I also wanted to check if someone on the team had updated the workflow.yml file. To my surprise, no one had made any changes, yet the libssl1.1 installation was failing.
I committed the changes and pushed them to GitHub, then checked the Actions page again. This time, I encountered a different error:
Run sudo apt-get install -y xfonts-base xfonts-75dpi libssl1.1
Reading package lists...
Building dependency tree...
Reading state information...
Package libssl1.1 is not available, but is referred to by another package.
This may mean that the package is missing, has been obsoleted, or
is only available from another source
E: Package 'libssl1.1' has no installation candidate
Searching for a Solution
After checking this issue on Google, I came across a suggestion to install libssl-dev instead of libssl1.1. I tried that, but I still encountered the same error as above.
While carefully reading the workflow.yml file, I noticed this configuration:
jobs:
build:
runs-on: ubuntu-latest
It turns out that someone on the team had configured ubuntu-latest about six years ago, which at that time pointed to an Ubuntu 2018 version. I checked the Actions repository on GitHub and found that the ubuntu-latest tag now points to Ubuntu 2022. However, it was 2025, and it seemed that the GitHub team had updated ubuntu-latest to Ubuntu 2024, but had not updated the README to reflect this change. This version mismatch was likely causing the build to fail.
The Fix
To resolve the issue, I updated the runs-on tag in the workflow configuration to target a specific Ubuntu version that I knew was stable:
jobs:
build:
runs-on: ubuntu-22.04
Since the build was running successfully until January 7, 2025, I decided to use Ubuntu 22.04. After making this change, the wkhtmltopdf installation was successful, and the build passed without any issues.
Conclusion
By updating the runs-on tag to a specific and stable Ubuntu version, I was able to resolve the dependency issues with wkhtmltopdf and get our GitHub Actions pipeline back on track. This experience highlights the importance of being mindful of external dependencies and how they can affect your CI/CD pipelines, even if you haven’t made any changes to your code.
I hope this blog post helps others who might encounter similar issues with GitHub Actions and dependency management. Happy coding!