Fix "No Usable Sandbox" in Puppeteer on GitHub Actions
Puppeteer fails with "No usable sandbox" on ubuntu-24.04 runners because AppArmor blocks user namespaces. Three fixes, from safest to quickest, with checks.
At a glance
- Last reviewed
- Versions referenced
actions/checkout@v7actions/setup-node@v7- Reading time
- 2 min read
Code samples are not run in a live repository. See our editorial standards.
On this page
Puppeteer fails with No usable sandbox! on GitHub Actions because Ubuntu 24.04 restricts unprivileged user namespaces through AppArmor, and Chrome needs them for its sandbox. The quickest fix is to lift the restriction for the job with sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0. If you prefer not to change the kernel setting, allow only Puppeteer’s Chrome with an AppArmor profile, or fall back to --no-sandbox.
name: puppeteer
on: [push]
jobs:
test:
runs-on: ubuntu-24.04
steps:
- uses: actions/checkout@v7
- uses: actions/setup-node@v7
with:
node-version: '22'
- name: Allow unprivileged user namespaces
run: sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0
- run: npm ci
- run: npm test
The sysctl applies to the whole runner VM until the job ends. GitHub-hosted runners are ephemeral, so nothing persists to other jobs.
Why it happens
Ubuntu 23.10 and later ship with kernel.apparmor_restrict_unprivileged_userns=1. Unprivileged processes can still create user namespaces, but AppArmor strips their capabilities inside them unless a profile grants the userns permission. Chrome’s sandbox depends on that permission, so launch fails. Puppeteer surfaces it as Failed to launch the browser process! followed by the sandbox message.
The ubuntu-22.04 image does not have this restriction. If the error appeared when you moved to ubuntu-latest and it now resolves to 24.04, this is your cause.
Missing shared libraries produce a different failure, usually an error while loading shared libraries line. Installing more apt packages will not fix a sandbox error.
Fix 1: lift the restriction for the job
Use the sysctl step shown above. It is one line and keeps Chrome’s sandbox enabled, so no launch flags change.
To verify, add a step right after it:
- name: Check sysctl
run: sysctl kernel.apparmor_restrict_unprivileged_userns
The log should print kernel.apparmor_restrict_unprivileged_userns = 0. Then run your tests and confirm the browser launches.
Fix 2: allow only Puppeteer’s Chrome with an AppArmor profile
This keeps the restriction on for everything else on the runner. Write a profile that grants userns to the Chrome binary that Puppeteer downloads, then load it.
- name: Allow userns for Puppeteer Chrome
run: |
sudo tee /etc/apparmor.d/puppeteer-chrome > /dev/null <<'EOF'
abi <abi/4.0>,
include <tunables/global>
profile puppeteer-chrome /home/runner/.cache/puppeteer/chrome/**/chrome flags=(unconfined) {
userns,
}
EOF
sudo apparmor_parser -r /etc/apparmor.d/puppeteer-chrome
This assumes the default cache location, ~/.cache/puppeteer, which is /home/runner/.cache/puppeteer on GitHub-hosted runners. If you set PUPPETEER_CACHE_DIR or executablePath, change the profile path to match. A path that does not match the real binary leaves the error in place.
To verify, run sudo apparmor_parser -r and check that it exits with status 0. Then launch the browser. If it still fails, compare the profile path with the output of puppeteer.executablePath().
Fix 3: pass --no-sandbox
Use this when you cannot change the runner’s AppArmor settings, for example on a self-hosted runner you do not control, or when Chrome runs as root inside a container.
const puppeteer = require('puppeteer');
const isCI = process.env.GITHUB_ACTIONS === 'true';
async function launchBrowser() {
return puppeteer.launch({
args: isCI ? ['--no-sandbox'] : [],
});
}
module.exports = { launchBrowser };
--no-sandbox removes the isolation between the page and the runner. A malicious page could reach the job’s environment variables and GITHUB_TOKEN. Use it only when the pages you load are your own or otherwise trusted, never for arbitrary URLs.
--disable-setuid-sandbox is not needed for this error. It only disables the older SUID sandbox, which you are not using.
Verify the fix
Run a minimal launch script as a step before your full test suite:
const puppeteer = require('puppeteer');
(async () => {
const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.goto('about:blank');
console.log('Chrome version:', await browser.version());
await browser.close();
})();
If the step prints a Chrome version: line and exits with code 0, the sandbox problem is gone. If you still see Failed to launch the browser process!, read the lines after it. They name the actual cause, which is a different problem if the sandbox message is absent.
Spotted an error? Report it on our Contact page and see our editorial standards for how we correct articles.