Plugin Compatibility

At 09:14 an operator upgrades Grafana from 11.0.0 to 11.4.0 on a deployment that has three community plugins installed. The service starts cleanly. The team opens a dashboard that uses the marcusolsson-json-datasource plugin and sees the panel render as a grey box with the legend “Plugin not found”. The plugin is still listed in grafana cli plugins ls — but the new Grafana refuses to load it.

The root cause is a plugin SDK bump in Grafana 11.4.0. The plugin was built against the Grafana 11.0 SDK. The new SDK introduced a breaking change to the datasource response contract that the older plugin does not implement. The plugin author has released a 1.4.0 version that targets the new SDK; the team’s installation is pinned to 1.3.1. The discipline that prevents this is matching the plugin SDK to the Grafana SDK before the upgrade, not after.

What Grafana plugin compatibility is

Grafana plugins are compiled against a plugin SDK that Grafana ships with each release. The SDK is the contract between the plugin and the host: it defines the datasource response shape, the panel lifecycle hooks, the authentication extension points, and the alert evaluator entry points.

A plugin’s SDK version is encoded in its plugin.json manifest:

{
  "id": "marcusolsson-json-datasource",
  "name": "JSON API",
  "version": "1.3.1",
  "sdk": {
    "version": "11.0.0",
    "dependencies": {
      "grafanaDependency": ">=11.0.0"
    }
  }
}

The sdk.version field is the SDK the plugin was compiled against. The grafanaDependency field is the minimum Grafana version the plugin is willing to load against. There is no maximum declared; the plugin author assumes the SDK is forward-compatible.

Forward compatibility is not a guarantee. A Grafana release that introduces a breaking change to the SDK will reject plugins built against the older SDK. The plugin must be upgraded to a version that targets the new SDK before the Grafana upgrade can proceed.

Why a sysadmin cares

Three operational pains the discipline prevents:

• Silent plugin failure on a minor bump. A Grafana minor release that introduces an SDK breaking change will load the affected plugin at startup, but the plugin’s panels will not render data. Symptom: dashboards that worked before the upgrade load with “Plugin not found” or with panels that query but never return data. The Grafana log records the SDK mismatch as a warning; the operator has to read the log to find it.
• Plugin dependency on a removed Grafana feature. A plugin that uses a Grafana API removed in the target release will fail to load entirely. Symptom: Grafana starts but the plugin is missing from grafana cli plugins ls because the binary has refused to load it.
• Unsigned plugin rejected by a stricter default. Grafana 11.x enforces plugin signature verification for catalog plugins. A plugin installed manually (a zip file dropped into the plugins directory) will fail to load unless the operator has set allow_loading_unsigned_plugins. Symptom: the plugin is in the directory but Grafana reports plugin signature verification failed.

The cost of the discipline is roughly ten minutes per plugin per upgrade. The cost of skipping it is a dashboard that silently stops rendering data.

How it works: the plugin loading order

The plugin loading order matters because it determines where in the log the operator finds the evidence:

1. Grafana binary starts
       |
2. Read /etc/grafana/grafana.ini [plugins] section
       |
3. Scan the plugin directory (default /var/lib/grafana/plugins)
       |
4. For each plugin:
       |   - Read plugin.json
       |   - Verify signature (if enabled)
       |   - Check SDK version against the binary's SDK
       |   - If compatible, register the plugin
       |   - If incompatible, log a warning and skip
       |
5. Plugins registered: list goes into the plugin registry
       |
6. HTTP server starts
       |
7. UI loads, dashboard panels resolve plugins by id
       |
8. Panel render fails if the plugin id is not in the registry

The failure point at step 4 is the silent one. The plugin is on disk; the plugin id is referenced by a dashboard; the dashboard panel tries to resolve the plugin and fails. The operator sees a grey box. The Grafana log has the warning that explains the cause.

How to configure it: the plugin discipline

The plugin discipline has four steps. The team runs all four before every Grafana upgrade that crosses a minor boundary.

Step 1: enumerate the installed plugins. The catalog of what the team has:

# READ-ONLY: list every plugin and its version.
grafana cli plugins ls
# installed: yes
# id: grafana-clock-panel, version: 1.3.0
# id: grafana-piechart-panel, version: 1.6.4
# id: marcusolsson-json-datasource, version: 1.3.1
# id: volkovlabs-echarts-panel, version: 6.5.0

Step 2: look up each plugin’s SDK target. The catalog page for each plugin lists the Grafana versions it supports. The team records the answer in the upgrade plan:

# upgrades/2026-09-grafana-11.4.0-plugins.yaml
plugins:
  - id: grafana-clock-panel
    installed_version: 1.3.0
    catalog_page: 'https://grafana.com/grafana/plugins/grafana-clock-panel'
    sdk_target: '11.x'
    upgrade_path: 'latest from catalog'
  - id: marcusolsson-json-datasource
    installed_version: 1.3.1
    catalog_page: 'https://grafana.com/grafana/plugins/marcusolsson-json-datasource'
    sdk_target: '11.0.0 to 11.3.0'
    upgrade_path: 'upgrade to 1.4.0 before Grafana 11.4'

Step 3: upgrade the plugins first. The plugins are upgraded before the Grafana upgrade, on the running Grafana. This isolates the plugin change from the Grafana change.

# CONFIGURATION: upgrade a single plugin. The Grafana
# process restarts only the plugin, not the whole service.
grafana cli plugins upgrade marcusolsson-json-datasource 1.4.0

Step 4: verify the plugins on the canary. After the Grafana upgrade on the canary host, the team checks that every plugin is registered and that a representative dashboard for each plugin still renders.

The Grafana configuration for plugin management. The relevant section in /etc/grafana/grafana.ini:

[plugins]
# The plugin directory. The default is correct for most
# installations; only override for containerised deployments
# that mount a different volume.
path = /var/lib/grafana/plugins

# Disable plugins by id, comma-separated. Useful when retiring
# a plugin but still need time to remove it from dashboards.
disable_plugin = deprecated-plugin-id

# Whether to allow plugins installed by dropping a zip file
# into the plugins directory. The default is false. Setting
# this to true is a security risk; do it only for a known,
# short window during a plugin upgrade.
allow_loading_unsigned_plugins = false

How to validate it

The minimum validation set for a Grafana upgrade that includes plugin work. Every command is READ-ONLY unless flagged otherwise:

# READ-ONLY: confirm the plugin set is what the team expects
# after the upgrade.
grafana cli plugins ls
# installed: yes
# id: grafana-clock-panel, version: 1.3.0
# id: grafana-piechart-panel, version: 1.6.4
# id: marcusolsson-json-datasource, version: 1.4.0
# id: volkovlabs-echarts-panel, version: 6.5.0

# READ-ONLY: confirm every plugin reports a healthy health
# check. The /api/datasources endpoint includes the health
# status for each datasource.
curl -fsS -u admin:admin \
  http://grafana-canary-01:3000/api/datasources | \
  jq '.[] | {id, name, type, health}'
# {"id":1,"name":"Prometheus","type":"prometheus","health":"OK"}
# {"id":2,"name":"Loki","type":"loki","health":"OK"}
# {"id":3,"name":"JSON-API","type":"marcusolsson-json-datasource",
#  "health":"OK"}

# READ-ONLY: confirm the plugin registry is healthy. The
# /api/plugins endpoint returns the registry contents.
curl -fsS -u admin:admin \
  http://grafana-canary-01:3000/api/plugins | \
  jq '.[] | select(.signature != "valid") | {id, signature}'
# (empty output means every plugin has a valid signature)

# READ-ONLY: confirm the Grafana log has no plugin warnings
# since the upgrade.
journalctl -u grafana-server --since "1 hour ago" | \
  grep -i "plugin" | grep -i "warn\|error" || echo "no warnings"

The validation order matters: plugin list first, health check second, signature verification third, log scan fourth. The team should not consider the plugin discipline complete until every plugin in the list matches the pre-upgrade catalogue.

How it can fail

Five failure modes recur in Grafana plugin upgrades.

1. Plugin SDK out of date. A plugin pinned to Grafana 11.0 fails to load on Grafana 11.4 because the SDK breaking change is not backward-compatible. Symptom: the plugin is in the directory but Grafana refuses to register it; the panel renders as “Plugin not found”.
2. Plugin signature rejected. A plugin installed manually (a zip file dropped into the directory) has no signature. Grafana 11.x refuses to load it by default. Symptom: the Grafana log records plugin signature verification failed; the plugin is missing from grafana cli plugins ls.
3. Plugin health check fails after upgrade. A plugin that loaded under the old Grafana fails its health check under the new Grafana because the new SDK requires a stricter response shape. Symptom: the datasource shows “Down” in the UI; “Test connection” fails.
4. Plugin dependency on a removed feature. A plugin that uses a Grafana API removed in the target release fails to load at all. Symptom: Grafana starts but the plugin is missing from the registry.
5. No plugin upgrade path. A plugin’s author has not released a version that targets the new Grafana SDK. Symptom: the team has to choose between staying on the old Grafana version, removing the plugin, or forking it.

How to troubleshoot it

When a plugin fails to load after an upgrade, the diagnostic order matters. Start at the plugin view and move toward the dashboard view.

1. Is the plugin in the registry? Run grafana cli plugins ls. If the plugin is missing, the binary has refused to load it. Read the Grafana log for the reason.
2. What does the Grafana log say? Read journalctl -u grafana-server. Look for plugin signature verification failed, plugin SDK version mismatch, failed to load plugin.
3. What does the plugin’s plugin.json say? Read /var/lib/grafana/plugins/<id>/plugin.json. Confirm the sdk.version field and the grafanaDependency field.
4. What does the catalog say? Open the plugin’s catalog page in a browser. Find the “Compatibility” or “Versions” tab. Confirm the latest version targets the Grafana SDK the team is upgrading to.
5. Form a hypothesis. Pin the failure to one of the five failure modes above. The most common is “plugin SDK out of date”.
6. Find evidence. Compare the installed version against the catalog’s latest version. If the catalog has a newer version, the upgrade path is to install it.
7. Test the hypothesis. Run grafana cli plugins upgrade <id> <version> against the canary host. Restart the binary. Confirm the plugin loads.

The diagnostic order is “is the plugin registered before asking whether the plugin works.”

Security implications

Three security implications are specific to Grafana plugin work:

• Plugin signature verification. Grafana 11.x enforces signature verification for catalog plugins. Plugins installed manually (zip files) must be explicitly allowed via allow_loading_unsigned_plugins. The default of false is correct for production.
• Plugin sandbox escapes. Grafana plugins run in a restricted environment but the sandbox has had CVEs. A Grafana security upgrade may include a plugin sandbox fix. The discipline of reading the release note catches this; the discipline of patching on a known cadence prevents it from accumulating.
• Plugin datasource credentials. A datasource plugin stores its credentials in the Grafana database. A plugin that has been compromised can read those credentials. The discipline of plugin allowlisting (only install plugins from the official catalog, or from authors the team has reviewed) limits the exposure.

Performance implications

Performance implications of a Grafana plugin upgrade are not symmetric with the upgrade’s risk:

• Plugin load time. A Grafana instance with many plugins takes longer to start because each plugin’s Go binary is loaded at startup. The team should audit the plugin list quarterly and remove plugins no one uses.
• Query latency. A plugin that has been upgraded to a newer SDK can produce smaller frames or better batching, which can reduce query latency. The opposite is also possible: a plugin upgrade that introduces a less efficient query path can increase latency. The validation step is where the team notices.
• Memory footprint. Each loaded plugin consumes memory. A Grafana instance with twenty plugins loaded consumes measurably more memory than one with five. The team should measure the memory footprint before and after a plugin change.

The release note will not call out performance implications of plugin work specifically. The validation step is where the team notices.

Production guidance

• Use the catalog. Every plugin should be installed from the official Grafana plugin catalog. Manual zip installs bypass signature verification and bypass the catalog’s compatibility matrix.
• Upgrade plugins before Grafana. Plugins are upgraded first, on the running Grafana. The Grafana binary upgrade follows only after the plugin set is known to be compatible.
• Pin plugin versions in IaC. The team’s provisioning system should pin every plugin to a specific version. A wildcard version (* or latest) will drift between staging and production.
• Remove unused plugins. Every plugin loaded into the Grafana binary is attack surface. The team should remove plugins that no dashboard uses.

Verification

You should now be able to answer:

• What does the sdk.version field in a Grafana plugin’s plugin.json tell you?
• Why must plugins be upgraded before the Grafana binary, not after?
• What four things does the grafana cli plugins ls command show?
• Why is a plugin signature verification failure a security signal, not just an operational one?

Quiz