Email and PDF Issues Again 2026

Uncategorized
1

Fixing Manager.io Docker “PuppeteerSharp Failed to Launch Browser” When Sending Emails

I was getting an internal error in Manager.io when trying to email a customer:

PuppeteerSharp.ProcessException: Failed to launch browser!

The problem turned out to be the Chromium browser used by PuppeteerSharp for generating PDFs. The cronet/manager.io:latest Docker image was missing some Chromium dependencies, and the container was running Manager as root.

Environment

  • Docker

  • cronet/manager.io:latest

  • Manager.io 26.1.21.3171

  • Debian 11 (Bullseye) inside the container

1. Fix the Debian package repositories

The original image was using Debian Bullseye repositories that were returning 404 errors when trying to install the Chromium dependencies.

I changed /etc/apt/sources.list to use a Debian snapshot:

deb http://snapshot.debian.org/archive/debian/20250113T000000Z bullseye main
deb http://snapshot.debian.org/archive/debian-security/20250113T000000Z bullseye-security main
deb http://snapshot.debian.org/archive/debian/20250113T000000Z bullseye-updates main

The snapshot repository requires the Valid-Until check to be disabled:

apt-get -o Acquire::Check-Valid-Until=false update

2. Create a custom Manager Docker image

Rather than modifying the running Manager container, I created a custom image based on the Manager image.

Create a directory:

mkdir manager-fixed
cd manager-fixed

Create a file called Dockerfile:

FROM cronet/manager.io:latest

# Debian Bullseye packages have moved, use a snapshot repository
RUN printf "deb http://snapshot.debian.org/archive/debian/20250113T000000Z bullseye main\n\
deb http://snapshot.debian.org/archive/debian-security/20250113T000000Z bullseye-security main\n\
deb http://snapshot.debian.org/archive/debian/20250113T000000Z bullseye-updates main\n" > /etc/apt/sources.list

# Install Chromium/Puppeteer dependencies
RUN apt-get -o Acquire::Check-Valid-Until=false update && \
    apt-get -o Acquire::Check-Valid-Until=false install -y \
    libglib2.0-0 \
    libnss3 \
    libatk1.0-0 \
    libatk-bridge2.0-0 \
    libcups2 \
    libdrm2 \
    libdbus-1-3 \
    libxkbcommon0 \
    libxcomposite1 \
    libxdamage1 \
    libxfixes3 \
    libxrandr2 \
    libgbm1 \
    libasound2 \
    libpangocairo-1.0-0 \
    libgtk-3-0 && \
    rm -rf /var/lib/apt/lists/*

# Manager was running as root. Create a non-root user.
RUN useradd -m -u 1000 manager

# PuppeteerSharp creates/uses this directory for Chromium
RUN mkdir -p /PuppeteerSharp && \
    chown -R 1000:1000 /PuppeteerSharp && \
    chown -R 1000:1000 /home/manager

ENV HOME=/home/manager

USER manager

Build the image:

sudo docker build --no-cache -t manager-fixed .

3. Keep Manager’s data outside the container

Example Manager data directory is:

/srv/manager-server/data

and it is mounted into the container as:

/data

The Docker mount is:

/srv/manager-server/data:/data

This is important because recreating the container will not remove the Manager data.

Before changing containers, I recommend making a backup:

sudo tar -czf manager-backup-$(date +%F).tar.gz /srv/manager-server/data

4. Run Manager as the non-root user

Stop and remove the old container:

sudo docker stop manager.io
sudo docker rm manager.io

Then launch the custom image:

sudo docker run -d \
  --name manager.io \
  --restart unless-stopped \
  --shm-size=1gb \
  --cap-add=SYS_ADMIN \
  -p 8080:80 \
  -v /srv/manager-server/data:/data \
  manager-fixed

Important: --cap-add=SYS_ADMIN

This turned out to be the final piece for Chromium’s sandbox.

Without it, Chromium failed with:

No usable sandbox!

Adding:

--cap-add=SYS_ADMIN

allowed Chromium to use its sandbox while Manager continued running as the non-root manager user.

I did not need to use:

--no-sandbox

and I did not need to change the chrome-sandbox permissions.

5. What the individual errors meant

Error 1 — Missing Chromium library

Initially Chromium would not start:

error while loading shared libraries:
libglib-2.0.so.0: cannot open shared object file

The solution was installing the required Chromium libraries.

Error 2 — Debian package 404 errors

apt was returning errors such as:

404 Not Found

for the Bullseye packages.

The solution was switching the container to the Debian snapshot repositories and using:

-o Acquire::Check-Valid-Until=false

Error 3 — Chromium running as root

After installing the libraries, Manager produced:

Running as root without --no-sandbox is not supported

The container was running as:

uid=0(root)

The solution was creating a dedicated user:

RUN useradd -m -u 1000 manager
USER manager

Error 4 — PuppeteerSharp directory permissions

After switching to the non-root user:

Access to the path '/PuppeteerSharp' is denied

The solution was:

RUN mkdir -p /PuppeteerSharp && \
    chown -R 1000:1000 /PuppeteerSharp

Error 5 — Chromium sandbox

The final error was:

No usable sandbox!

The solution was adding this to the Docker launch command:

--cap-add=SYS_ADMIN

After adding that, Manager’s PDF generation and customer email functionality worked.

Final working configuration

The important pieces are:

Custom image

cronet/manager.io:latest
        ↓
Chromium dependencies installed
        ↓
non-root manager user
        ↓
writable /PuppeteerSharp

Docker launch

sudo docker run -d \
  --name manager.io \
  --restart unless-stopped \
  --shm-size=1gb \
  --cap-add=SYS_ADMIN \
  -p 8080:80 \
  -v /srv/manager-server/data:/data \
  manager-fixed

With this configuration:

  • Manager runs as a non-root user

  • Chromium runs with its sandbox enabled

  • No --no-sandbox workaround is required

  • PuppeteerSharp can access its browser directory

  • PDF generation works

  • Customer emails work

  • Manager data remains in /srv/manager-server/data

Hopefully this helps anyone else running Manager.io in Docker who encounters the same PuppeteerSharp/Chromium launch error.

2 Likes