mediumFoundationSymptom-first#grafana#dashboard#import#plugin#schema

Grafana dashboard import fails — JSON schema version mismatch or missing plugin

Grafana import page shows 'Dashboard init failed' or 'Invalid dashboard JSON'

Likely source:configurationdeployment

Focused incident mode — strips away everything but this runbook.

Symptoms

  • Grafana import page shows 'Dashboard init failed' or 'Invalid dashboard JSON'
  • Import succeeds but panels are broken with 'Plugin not found' errors
  • Dashboard schema version is higher than the Grafana instance supports
  • Panels using a newer panel type (e.g., geomap, traces) appear as raw JSON

Always compare the schemaVersion in the exported JSON with the target Grafana version before importing. Dashboards exported from Grafana 10+ may not import into Grafana 9 without downgrading the schema.

Evidence to grab

Collect these artifacts before you change anything — they prove (or rule out) each cause.

  • Grafana version and API health

    curl -s http://<GRAFANA>/api/health | jq '{version, database}'

  • Dashboard JSON schema version

    jq '.schemaVersion' <DASHBOARD-EXPORT.json

Diagnostic flow

Run the steps in order, marking each claim confirmed or refuted. The evidence you gather feeds the ranked causes below.

Guided decision tree is ready.

Steps with commands, expected output, and pass/fail branches.

Ranked root causes

Evidence checklist

  • schemaVersion in the JSON is higher than what the Grafana version supports
  • Import error explicitly mentions schema version
  • Dashboard was exported from a newer Grafana instance

Confirm before fixing

curl -s http://<GRAFANA>/api/health | jq '.version'
READ

Confirm Grafana version

Fix

helm upgrade grafana grafana/grafana -n monitoring --set image.tag=<NEWER-VERSION>
CHANGE

Upgrade Grafana to a version that supports the dashboard schema

Resolution runbook

Apply from top to bottom after the cause is confirmed. Review every command before running it — risk tags are shown on each.

1
curl -s http://<GRAFANA>/api/health | jq '.version'
READ

Check Grafana version

2
jq '.schemaVersion' <DASHBOARD-EXPORT.json
READ

Check dashboard schema version

3
jq '[.panels[].type] | unique' <DASHBOARD-EXPORT.json
READ

Identify required panel types

4
curl -s -H 'Authorization: Bearer <TOKEN>' http://<GRAFANA>/api/plugins | jq '.[] | .id'
READ

Verify installed plugins match required types

Prevention

  • Export dashboards as 'JSON Model' (not 'Share externally') when staying within the same Grafana version.
  • Document the required Grafana version and plugins in the dashboard README.
  • Use Grafana provisioning (YAML) for dashboards that must be consistent across environments.
  • Keep a known-good export of critical dashboards in version control.

Related runbooks

Same stack, same failure family — worth a skim.

Grafana dashboard panel shows 'Datasource with UID ... not found' after migrationhigh

Dashboard panels display 'Datasource with UID <uid> not found'

GrafanaIntermediate3 causes
Open runbook
Grafana dashboard panels show 'No data' — query returns empty resultsmedium

Dashboard panels display 'No data' or an empty chart

GrafanaFoundation3 causes
Open runbook

Commands marked READ CHANGE DESTRUCTIVE — never run DESTRUCTIVE commands against production data you cannot restore. Copy → verify → execute.