Error generating Mermaid diagrams with Asciidoctor-pdf and asciidoctor-diagrams

Question

I have the following step definition in my GitHub workflow

      - name: Convert AsciiDoc to PDF
        run: |
          set -o pipefail
          OUTPUT=$(asciidoctor-pdf -r asciidoctor-diagram -a allow-uri-read -a ./book/mybook.adoc 2>&1)
          echo "$OUTPUT"
          if echo "$OUTPUT" | grep -i -E "error.*image|could not generate image|failed to generate image"; then
            echo "Error: Image generation failed in asciidoctor-pdf output."
            exit 1
          fi

The actual command is:

asciidoctor-pdf -r asciidoctor-diagram -a allow-uri-read -a ./mybook.adoc

The rest of the step is to fail the step when something went wrong generating the PDF. This is how I know that the generation of the diagrams fails. This is the ouput I get:

asciidoctor: ERROR: mybook.adoc: line 32: Failed to generate image: mmdc failed: 
Error: Failed to launch the browser process!
[0614/214640.510905:FATAL:setuid_sandbox_host.cc(163)] The SUID sandbox helper binary was found, but is not configured correctly. Rather than run without sandboxing I'm aborting now. You need to make sure that /opt/google/chrome/chrome-sandbox is owned by root and has mode 4755.
TROUBLESHOOTING: https://pptr.dev/troubleshooting
    at ChildProcess.onClose (file:///opt/hostedtoolcache/node/22.16.0/x64/lib/node_modules/@mermaid-js/mermaid-cli/node_modules/@puppeteer/browsers/lib/esm/launch.js:303:24)
    at ChildProcess.emit (node:events:530:35)
    at ChildProcess._handle.onexit (node:internal/child_process:293:12)

On my local machine (running Windows 11) that command works, and diagrams are generated.

I checked the links suggested in the output, but can't find a solution for this problem.

I tried adding based on the information from those links:

sudo sysctl -w kernel.unprivileged_userns_clone=1
chromium-browser --no-sandbox --version || google-chrome --no-sandbox --version
export CHROME_DEVEL_SANDBOX=/opt/google/chrome/chrome-sandbox

The Linux version is: Ubuntu 24.04.2 LTS The Chromium browser is: Chromium 137.0.7151.0

I'm not an expert on Linux, so I suspect that I am misinterpreting the information on the links.

Thanks in advance for helping me out.

Answer 1

I've faced something similar (well, issues with Chromium on GH Actions). Yours is failing becos the Chromium sandbox isn't correctly setup. So, you have two options: 1. Properly install chrome and configure the sandbox, or 2. Just disable sandbox!

Option 1: Install Chrome + configure sandbox

1. Install Google Chrome / or Chromium and it's sandbox helper
2. Copy and set perms on the sandbox helper
3. Export the env var to point to it
4. Then run asciidoctor-pdf as normal

Add this before your asciidoctor-pdf step in the workflow:

- name: Setup Chrome sandbox for diagram rendering
  run: |
    apt-get update
    apt-get install -y google-chrome-stable
    CHROME_SANDBOX=$(dirname "$(which google-chrome-stable)")/chrome-sandbox
    sudo chown root:root "$CHROME_SANDBOX"
    sudo chmod 4755 "$CHROME_SANDBOX"
    echo "CHROME_DEVEL_SANDBOX=$CHROME_SANDBOX" >> $GITHUB_ENV

Then your diagram step stays the same:

- name: Convert AsciiDoc to PDF
  run: |
    set -o pipefail
    OUTPUT=$(asciidoctor-pdf -r asciidoctor-diagram -a allow-uri-read -a ./mybook.adoc 2>&1)
    echo "$OUTPUT"
    if echo "$OUTPUT" | grep -i -E "error.*image|could not generate image|failed to generate image"; then
      echo "Error: Image generation failed in asciidoctor-pdf output."
      exit 1
    fi

So, this should ensure that Puppeteer can launch Chrome with a properly permissioned sandbox.

---

Option 2: Just disable sandbox (less secure, simpler)

This should actually be fine in GH actions runners, and is much easier. You can just bypass the issue with a Puppeteer config.

1. Create a file puppeteer-config.json with:

{ "args": ["--no-sandbox", "--disable-setuid-sandbox"] }

2. Tell Asciidoctor Diagram to use it:

- name: Convert AsciiDoc to PDF (no sandbox)
  run: |
    export ASCIIDOCTOR_DIAGRAM_PUPPETEER_CONFIG=./puppeteer-config.json
    OUTPUT=$(asciidoctor-pdf -r asciidoctor-diagram -a allow-uri-read -a ./mybook.adoc 2>&1)
    ...

Or, pass it directly via an attribute in the AsciiDoc command

---

TL;DR

- name: Setup Chrome sandbox
  run: |
    apt-get update
    apt-get install -y google-chrome-stable
    CHROME_SANDBOX=$(dirname "$(which google-chrome-stable)")/chrome-sandbox
    sudo chown root:root "$CHROME_SANDBOX"
    sudo chmod 4755 "$CHROME_SANDBOX"
    echo "CHROME_DEVEL_SANDBOX=$CHROME_SANDBOX" >> $GITHUB_ENV

- name: Convert AsciiDoc to PDF
  run: |
    set -o pipefail
    OUTPUT=$(asciidoctor-pdf -r asciidoctor-diagram -a allow-uri-read -a ./mybook.adoc 2>&1)
    echo "$OUTPUT"
    if echo "$OUTPUT" | grep -i -E "error.*image|could not generate image|failed to generate image"; then
      echo "Error: Image generation failed in asciidoctor‑pdf output."
      exit 1
    fi

or

- name: Convert AsciiDoc to PDF (with no-sandbox diagrams)
  env:
    # Tell Puppeteer (used by asciidoctor-diagram) to skip sandbox
    PUPPETEER_ARGS: "--no-sandbox --disable-setuid-sandbox"
  run: |
    set -o pipefail
    OUTPUT=$(asciidoctor-pdf \
      -r asciidoctor-diagram \
      -a allow-uri-read \
      -a ./mybook.adoc 2>&1)
    echo "$OUTPUT"
    if echo "$OUTPUT" | grep -i -E "error.*image|could not generate image|failed to generate image"; then
      echo "Error: Image generation failed in asciidoctor-pdf output."
      exit 1
    fi

Answer 2

Thanks @alicia-sykes, you put me on the right path.

The final GitHub step became:

      - name: Setup Chrome sandbox for diagram rendering
        run: |
          sudo sysctl -w kernel.unprivileged_userns_clone=1
          sudo apt-get update
          sudo apt-get install -y google-chrome-stable

          CHROME_SANDBOX=$(dirname "$(which google-chrome-stable)")/chrome-sandbox

          # Additional fallback paths because Chrome is not necessarily installed 
          # in the default location, but there are known alternatives.
          if [ ! -f "$CHROME_SANDBOX" ]; then
            echo "Attempting fallback paths for chrome-sandbox..."
            if [ -f "/opt/google/chrome/chrome-sandbox" ]; then
              CHROME_SANDBOX="/opt/google/chrome/chrome-sandbox"
            elif [ -f "/usr/lib/chromium-browser/chrome-sandbox" ]; then
              CHROME_SANDBOX="/usr/lib/chromium-browser/chrome-sandbox"
            else
              echo "Error: chrome-sandbox could not be found in any known locations."
              exit 1
            fi
          fi

          sudo chown root:root "$CHROME_SANDBOX"
          sudo chmod 4755 "$CHROME_SANDBOX"

          echo 'Exporting CHROME_DEVEL_SANDBOX environment variable...'
          echo "CHROME_DEVEL_SANDBOX=$CHROME_SANDBOX" >> $GITHUB_ENV

Once I added this step to the workflow, the generation of the mermaid diagrams in the AsciiDoctor file succeeded.