Introduction

Importing dashboards into Grafana is a common way to share visualizations or migrate configurations. Dashboard imports can fail for various reasons: the JSON file may be malformed, the dashboard may reference datasources that don't exist, or the dashboard version may be incompatible with your Grafana version. Understanding the specific error helps resolve the issue quickly.

Symptoms

  • Import button shows error: "Failed to import dashboard"
  • Error: "Invalid JSON" or "JSON parse error"
  • Dashboard imports but panels show "Datasource not found" errors
  • Import succeeds but panels display "Plugin not found" errors
  • Error: "Dashboard version mismatch" or "Unsupported schema version"
  • Imported dashboard has missing panels or broken queries

Common Causes

  • Dashboard JSON file is malformed or incomplete
  • Dashboard references datasource UIDs that don't exist in your Grafana
  • Dashboard requires plugins that are not installed
  • Dashboard schema version is newer than your Grafana version
  • Panel type requires a plugin version you don't have
  • Imported dashboard conflicts with existing dashboard with same UID

Step-by-Step Fix

Validate Dashboard JSON

  1. 1.Check if the dashboard JSON file is valid:
  2. 2.```bash
  3. 3.python3 -c "import json; json.load(open('dashboard.json'))"
  4. 4.`
  5. 5.If the JSON is invalid, identify the syntax error:
  6. 6.```bash
  7. 7.jq . dashboard.json
  8. 8.# jq will report specific syntax errors
  9. 9.`
  10. 10.Common JSON issues:
  11. 11.- Missing closing braces
  12. 12.- Unescaped special characters in strings
  13. 13.- Comments (JSON does not support comments)
  14. 14.- Encoding issues (ensure UTF-8)

Fix Datasource Mismatch

  1. 1.Identify datasource references in the dashboard:
  2. 2.```bash
  3. 3.grep -o '"datasource"[^}]*}' dashboard.json | head -20
  4. 4.`
  5. 5.Check datasources in your Grafana instance:
  6. 6.```bash
  7. 7.curl -s -u admin:password http://localhost:3000/api/datasources | jq '.[] | {name: .name, uid: .uid, type: .type}'
  8. 8.`
  9. 9.Map datasources during import:
  10. 10.- In the import dialog, Grafana shows a datasource mapping screen
  11. 11.- Select your local datasource for each referenced datasource in the dashboard
  12. 12.- If datasource is not listed, create it first
  13. 13.Alternatively, modify the dashboard JSON before import:
  14. 14.```bash
  15. 15.# Replace datasource UID in dashboard
  16. 16.sed -i 's/"uid": "old-uid"/"uid": "new-uid"/g' dashboard.json
  17. 17.`

Fix Plugin Requirements

  1. 1.Check for plugin dependencies in the dashboard:
  2. 2.```bash
  3. 3.grep -o '"type"[^,]*,' dashboard.json | sort -u
  4. 4.`
  5. 5.Install required plugins:
  6. 6.```bash
  7. 7.grafana-cli plugins install grafana-clock-panel
  8. 8.grafana-cli plugins install grafana-piechart-panel
  9. 9.`
  10. 10.For community plugins, check if they are available:
  11. 11.```bash
  12. 12.grafana-cli plugins list-repo | grep -i piechart
  13. 13.`
  14. 14.If plugin is not in the catalog, download and install manually:
  15. 15.```bash
  16. 16.wget https://github.com/grafana/piechart-panel/releases/download/v1.6.2/grafana-piechart-panel-1.6.2.zip
  17. 17.unzip grafana-piechart-panel-1.6.2.zip -d /var/lib/grafana/plugins/
  18. 18.systemctl restart grafana-server
  19. 19.`

Fix Version Compatibility

  1. 1.Check dashboard schema version:
  2. 2.```bash
  3. 3.jq '.schemaVersion' dashboard.json
  4. 4.`
  5. 5.Check your Grafana version:
  6. 6.```bash
  7. 7.grafana-cli --version
  8. 8.`
  9. 9.Dashboard schema version compatibility:
  10. 10.- Schema version 38+ requires Grafana 11+
  11. 11.- Schema version 37 requires Grafana 10+
  12. 12.- Schema version 36 requires Grafana 9+
  13. 13.If your Grafana is older, either upgrade Grafana or find an older dashboard version:
  14. 14.```bash
  15. 15.# Download older dashboard version from grafana.com
  16. 16.curl -s https://grafana.com/api/dashboards/1860/versions/1 | jq '.json' > dashboard-v1.json
  17. 17.`

Fix UID Conflicts

  1. 1.Check if dashboard UID already exists:
  2. 2.```bash
  3. 3.jq '.uid' dashboard.json
  4. 4.curl -s -u admin:password http://localhost:3000/api/dashboards/uid/existing-uid
  5. 5.`
  6. 6.If UID conflicts, modify the UID before import:
  7. 7.```bash
  8. 8.jq '.uid = "new-unique-uid"' dashboard.json > dashboard-modified.json
  9. 9.`
  10. 10.Or use overwrite option during import:
  11. 11.- In import dialog, check "Overwrite" if you want to replace existing dashboard

Import from Grafana.com

  1. 1.Import directly from Grafana dashboard catalog:
  2. 2.- Navigate to Dashboards > Import
  3. 3.- Enter dashboard ID from grafana.com (e.g., 1860 for Node Exporter)
  4. 4.- Configure datasource mapping
  5. 5.- Click Import
  6. 6.Import via Grafana.com API:
  7. 7.```bash
  8. 8.curl -s https://grafana.com/api/dashboards/1860/revisions/latest/download > dashboard.json
  9. 9.`

Import via API

  1. 1.Import dashboard using Grafana API:
  2. 2.```bash
  3. 3.curl -X POST -u admin:password \
  4. 4.-H "Content-Type: application/json" \
  5. 5.-d @dashboard.json \
  6. 6.http://localhost:3000/api/dashboards/import
  7. 7.`

Verification

  1. 1.After successful import:
  2. 2.- Navigate to the imported dashboard in Grafana
  3. 3.- Verify all panels load without errors
  4. 4.- Check each panel displays data from the correct datasource
  5. 5.- Test dashboard refresh and time range changes
  6. 6.Verify dashboard health:
  7. 7.```bash
  8. 8.curl -s -u admin:password http://localhost:3000/api/dashboards/uid/new-uid | jq '.meta | {status: .status, version: .version}'
  9. 9.`