🚨 Grafana Error Guide: 'Rendering plugin not available' — Install the Image Renderer

Overview

Grafana cannot render panels or dashboards to PNG images on its own. Server-side rendering — used by “Share > Direct link rendered image”, PDF export, and alert notification images — requires the separate Grafana Image Renderer plugin (a headless Chromium) or the standalone renderer service. When it is missing or unreachable, any render request fails.

The literal errors you will see:

Rendering plugin not available

logger=rendering error="Rendering plugin not available. Please make sure the plugin is installed and enabled. See https://grafana.com/docs/grafana/latest/setup-grafana/image-rendering/"

logger=rendering.http renderer=http error="Get \"http://localhost:8081/render?...\": dial tcp 127.0.0.1:8081: connect: connection refused"

It occurs the moment something asks Grafana for an image: an alert rule with images enabled fires, a user clicks the rendered-image share link, or a reporting job runs. The dashboard itself displays fine in the browser — only the server-side image path is broken.

Symptoms

• Alert notifications (Slack, email) arrive with no panel image, and the log shows Rendering plugin not available.
• “Share > Direct link rendered image” returns a broken image or the plain error text.
• Reporting / PDF export fails.
• grafana-cli plugins ls does not list grafana-image-renderer.

grafana-cli plugins ls | grep -i render

# (no output — plugin not installed)

Common Root Causes

1. The image renderer plugin is not installed

A fresh Grafana install has no rendering capability. Nothing renders until you add the plugin or the remote service.

grafana-cli plugins ls | grep render
ls /var/lib/grafana/plugins/grafana-image-renderer 2>/dev/null || echo "not installed"

2. The remote renderer service is configured but down or unreachable

When using the standalone grafana/grafana-image-renderer container, [rendering] server_url points at it. If that container is stopped or a firewall blocks the port, Grafana gets a connection error.

curl -s "http://localhost:8081/render/version"
docker ps --filter name=renderer --format '{{.Names}} {{.Status}}'

curl: (7) Failed to connect to localhost port 8081: Connection refused

3. Renderer installed but Chromium’s shared libraries are missing

On slim/Alpine base images the bundled Chromium fails to launch because of missing system libraries (e.g. libnss3, libX11). The plugin loads but every render crashes.

grep -i "rendering" /var/log/grafana/grafana.log | tail

logger=rendering.chrome error="Failed to launch the browser process ... error while loading shared libraries: libnss3.so: cannot open shared object file"

4. Callback URL wrong — renderer can’t reach Grafana back

The renderer service loads the dashboard by calling back to Grafana. If [rendering] callback_url (or the reverse-proxy root_url) is wrong, the render times out with a blank image.

Diagnostic Workflow

Step 1: Confirm whether the plugin/service exists

grafana-cli plugins ls | grep render
curl -s http://localhost:3000/api/health

Step 2: Reproduce the render directly

curl -s -H "Authorization: Bearer $GRAFANA_TOKEN" \
  "http://localhost:3000/render/d-solo/<uid>/<slug>?panelId=2&width=1000&height=500" \
  -o /tmp/render.png; file /tmp/render.png

A valid PNG image data means rendering works; HTML/text output contains the error.

Step 3: Check the rendering config

[rendering]
; For the bundled plugin, leave server_url empty.
; For the standalone service container:
server_url = http://renderer:8081/render
callback_url = http://grafana:3000/
concurrent_render_request_limit = 30

Step 4: Read the rendering logs

journalctl -u grafana-server --no-pager | grep -i render | tail -20
# Standalone renderer container:
docker logs grafana-renderer 2>&1 | tail -30

Step 5: Install the plugin if missing

grafana-cli plugins install grafana-image-renderer
systemctl restart grafana-server
grafana-cli plugins ls | grep render

Example Root Cause Analysis

An SRE reports that firing alerts no longer include panel screenshots. The Grafana log at alert-eval time:

logger=ngalert.notifier error="failed to take an image of the alert" err="Rendering plugin not available."

grafana-cli plugins ls shows no renderer. The team runs Grafana in Kubernetes from the grafana/grafana image and had assumed rendering was built in. Because the base image is slim, they deploy the dedicated renderer instead of installing the in-process plugin:

kubectl -n monitoring set image deploy/grafana-renderer \
  renderer=grafana/grafana-image-renderer:latest

Then point Grafana at it:

[rendering]
server_url = http://grafana-renderer:8081/render
callback_url = http://grafana:3000/

After kubectl rollout restart deploy/grafana, a test alert delivers with an image, and curl .../render/version on the renderer returns a JSON version. The fix: rendering is a separate component that must be explicitly deployed and wired with matching server_url/callback_url.

Prevention Best Practices

• Decide early: the in-process grafana-image-renderer plugin (simple, heavier on the Grafana pod) or the standalone renderer service (scales independently). In Kubernetes, prefer the standalone service.
• Health-check the renderer: probe http://<renderer>:8081/render/version and alert if it goes unreachable.
• Set callback_url/root_url correctly so the renderer can load dashboards back through your reverse proxy.
• Use the official renderer image (not slim) so Chromium’s shared libraries are present; test one render after every upgrade.
• Cap concurrent_render_request_limit so a flood of alert images can’t exhaust memory.
• See more Grafana guides and the sibling panel render timeout guide.

Quick Command Reference

# Is the plugin installed?
grafana-cli plugins ls | grep render

# Install the in-process renderer plugin
grafana-cli plugins install grafana-image-renderer
systemctl restart grafana-server

# Reproduce a render
curl -s -H "Authorization: Bearer $GRAFANA_TOKEN" \
  "http://localhost:3000/render/d-solo/<uid>/<slug>?panelId=2&width=1000&height=500" \
  -o /tmp/r.png; file /tmp/r.png

# Standalone renderer service
curl -s http://localhost:8081/render/version
docker logs grafana-renderer 2>&1 | tail -30

# Rendering logs
journalctl -u grafana-server | grep -i render | tail -20

Conclusion

Rendering plugin not available means Grafana was asked to produce an image but has no renderer to do it. Grafana never renders images itself. Typical root causes:

1. The grafana-image-renderer plugin (or standalone service) is simply not installed.
2. A configured remote renderer service is down or blocked by a firewall.
3. The renderer is installed but its bundled Chromium can’t launch (missing shared libraries).
4. A wrong callback_url/root_url prevents the renderer from loading the dashboard back through Grafana.

Confirm the plugin/service exists first, then reproduce a single /render request; the returned PNG-vs-error distinction tells you whether you’re chasing an install, a connectivity, or a Chromium problem.