Introduction

Grafana's image rendering plugin uses headless Chromium to generate PNG images of dashboard panels for alerts, reports, and sharing. When Chromium cannot start -- typically due to sandbox restrictions in Docker containers, missing dependencies, or incorrect permissions -- panel rendering fails. This breaks alert notifications that include rendered panel images and scheduled report delivery.

Symptoms

  • Alert notifications arrive without rendered panel images
  • Grafana logs show rendering failed: Failed to launch chrome or sandbox errors
  • /render endpoint returns 500 Internal Server Error
  • Image rendering plugin status shows error in the Grafana plugins page
  • Error message: Running as root without --no-sandbox is not supported

Common Causes

  • Grafana running as root user in a container, which Chromium blocks by default
  • Missing Chromium dependencies in the container image (libX11, libnss3, etc.)
  • Container security policy blocking Chromium sandbox system calls
  • Image renderer plugin not installed or misconfigured
  • Insufficient shared memory (/dev/shm) for Chromium rendering

Step-by-Step Fix

  1. 1.Check image renderer plugin status: Verify the plugin is installed and its state.
  2. 2.```bash
  3. 3.curl -s http://admin:admin@localhost:3000/api/plugins/grafana-image-renderer | jq '.info.version, .state'
  4. 4.`
  5. 5.Configure Chromium to run without sandbox in containers: Update the renderer configuration.
  6. 6.```ini
  7. 7.# grafana.ini
  8. 8.[plugin.grafana-image-renderer]
  9. 9.rendering_charset = utf-8
  10. 10.# Or set environment variable
  11. 11.# GF_RENDERING_ARGS="--no-sandbox --disable-gpu"
  12. 12.`
  13. 13.If running as root, add the --no-sandbox flag: Configure Chromium args.
  14. 14.```yaml
  15. 15.# Kubernetes deployment
  16. 16.env:
  17. 17.- name: GF_RENDERING_IGNORE_HTTPS_ERRORS
  18. 18.value: "true"
  19. 19.- name: GF_RENDERING_ARGS
  20. 20.value: "--no-sandbox --disable-setuid-sandbox --disable-gpu"
  21. 21.`
  22. 22.Increase shared memory for the container: Chromium needs adequate /dev/shm.
  23. 23.```yaml
  24. 24.# Kubernetes deployment
  25. 25.spec:
  26. 26.containers:
  27. 27.- name: grafana
  28. 28.volumeMounts:
  29. 29.- name: dshm
  30. 30.mountPath: /dev/shm
  31. 31.volumes:
  32. 32.- name: dshm
  33. 33.emptyDir:
  34. 34.medium: Memory
  35. 35.sizeLimit: 1Gi
  36. 36.`
  37. 37.Test panel rendering: Verify the fix works.
  38. 38.```bash
  39. 39.curl -s "http://localhost:3000/render/d-solo/dashboard-uid?panelId=1&width=1000&height=500" \
  40. 40.-o /tmp/panel-test.png
  41. 41.file /tmp/panel-test.png
  42. 42.# Should show: PNG image data
  43. 43.`

Prevention

  • Use the official grafana/grafana-image-renderer Docker image with correct Chromium configuration
  • Never run the image renderer as root -- use a dedicated non-root user
  • Include --no-sandbox flag only in containerized environments where sandbox is not available
  • Monitor image rendering success rate and alert on rendering failures
  • Test panel rendering after any Grafana or renderer plugin version upgrade
  • Set adequate shared memory limits for containers running the image renderer