Grafana Dashboard Migration: JSON Limits

JSON alone cannot automate the validation, dependency mapping, or semantic translation of a Grafana dashboard during migration—it only stores the dashboard’s structure and settings, not the logic for interpreting them across versions or data sources. This article explains what JSON can and cannot do in a Grafana dashboard migration, the practical gaps you will hit, and how to work around them.

What JSON Actually Stores in a Grafana Dashboard

A Grafana dashboard is a JSON document that defines panels, rows, variables, time ranges, and layout. The JSON schema includes fields like panels, templating, time, and schemaVersion. When you export a dashboard, you get this JSON file; when you import it, Grafana validates it against the current schema.

However, the JSON is a serialization of the dashboard model, not a full representation of the runtime environment. It references data sources by name or UID, but it does not contain the data source definitions themselves. It also stores queries in the syntax of the original data source—PromQL, InfluxQL, or SQL—but does not translate them if the target data source differs.

What JSON Cannot Do: The Core Gaps

During a migration, JSON alone fails in several key areas:

• Data source re-mapping: A dashboard pointing to Prometheus will not automatically switch to InfluxDB. JSON contains a reference (name or UID), but no translation logic for the query language.
• Schema version upgrades: Grafana evolves its schema. A dashboard from version 7 may have fields that are deprecated or changed in version 10. JSON import does not always convert these automatically; sometimes you must manually edit the file or use the Grafana API to update the schema version.
• Variable validation: Variables defined in JSON (e.g., a query variable that fetches label values) depend on the data source being reachable and the query returning valid results. JSON cannot validate that the query works against the new data source.
• Panel plugin compatibility: If a panel uses a plugin that is not installed on the target Grafana instance, the JSON import will fail or show an error. JSON does not include the plugin code.
• Alert rules and notifications: Alert rules are stored separately from the dashboard JSON in newer Grafana versions. Migrating a dashboard does not migrate the associated alerts or notification channels.

How Grafana Handles JSON Import: What Works

Grafana’s import process reads the JSON and creates a dashboard in the target instance. It will match data sources by name or UID if they exist. If the UID is missing, Grafana may prompt you to choose a data source manually. The import also preserves layout, panel sizes, and most visual settings.

For simple migrations—same Grafana version, same data source—JSON export/import works flawlessly. The dashboard appears exactly as it did before. This is the most common use case: moving a dashboard from a test instance to a production instance that uses the same stack.

Common Migration Scenarios and Their JSON Limitations

Real-world migrations often involve one of these scenarios:

• Grafana upgrade (e.g., 8.x to 10.x): JSON schema changes are usually backward-compatible, but some panel types or field overrides may be deprecated. You may need to manually edit the JSON to remove obsolete fields.
• Data source change (e.g., Prometheus to VictoriaMetrics): VictoriaMetrics is Prometheus-compatible, so queries work. But if you move from Prometheus to InfluxDB, the queries are not compatible. JSON cannot translate them.
• Multi-tenant migration: If you move dashboards between Grafana organizations, data source UIDs may differ. JSON references the UID, so you must update the UID in the JSON or use the import UI to remap.
• Automated migration via API: You can script the import using the Grafana HTTP API. But the API returns the same JSON validation errors you would see in the UI—it does not fix semantic issues.

How to Work Around JSON’s Limitations

To migrate successfully, you need to supplement JSON with manual steps:

1. Inventory your dashboards: List all data sources, plugins, and alert rules that each dashboard depends on.
2. Recreate data sources first: Create the same data sources in the target Grafana with the same names or UIDs. If UIDs differ, note them for remapping.
3. Install required plugins: Ensure all panel plugins are installed on the target instance.
4. Use the import UI’s data source mapping: When importing, Grafana lets you assign a new data source to each one in the dashboard.
5. Edit JSON for schema changes: If import fails, inspect the error message. Often it points to a specific field. Remove or update that field manually.
6. Test queries after import: Run each panel in edit mode to confirm queries return data. Fix any broken queries manually.
7. Recreate alert rules separately: Export alerts via the API or recreate them manually.

Costs and Risks of Relying on JSON Alone

The main cost is time. Manual remapping and query rewriting can take hours per dashboard. The risk is silent data corruption: a dashboard imports successfully but shows empty panels because the data source UID is wrong or the query syntax is incompatible.

Another risk is version drift. If you migrate dashboards frequently, you may end up with different schema versions across instances, making future migrations harder. It’s wise to keep a single source of truth for dashboards (e.g., a Git repository) and use Grafana’s provisioning system to deploy them via files, which gives you version control and auditability.

Alternatives to Manual JSON Migration

For complex migrations, consider these alternatives:

• Grafana Provisioning: Store dashboards as JSON files in a directory and let Grafana load them automatically. This is still JSON, but it is managed, versioned, and reproducible.
• Grafana API scripts: Write scripts to export dashboards, modify the JSON programmatically (e.g., replace data source UIDs), and import them. This automates the mechanical parts.
• Third-party tools: Some open-source tools exist to migrate dashboards between instances, but they essentially manipulate the same JSON—they do not magically translate queries.
• Manual rebuild: For a small number of dashboards, recreating them in the target instance may be faster than debugging JSON issues.

Frequently Asked Questions

Can I migrate a dashboard between different data sources (e.g., Prometheus to InfluxDB) using JSON?

No. JSON stores the query text in the original query language. You must manually rewrite each query to match the new data source’s syntax. The dashboard structure and layout will transfer, but the data queries will not work.

Why do I get a “schema version� error when importing a dashboard?

Grafana’s schema evolves. If the dashboard was exported from a much older version, it may contain fields that are no longer recognized. The import fails with a schema validation error. You can either edit the JSON to remove obsolete fields or use a tool like jq to update the schema version and adjust the structure.

Do alert rules migrate with the dashboard JSON?

In Grafana 8 and later, alert rules are stored separately from dashboards. Exporting a dashboard does not include its alert rules. You need to export alerts separately via the API or recreate them manually.

What is the safest way to migrate dashboards to a new Grafana instance?

Use the same Grafana version for both source and target, recreate the same data sources with identical UIDs, install all required plugins, and then import the JSON. After import, verify each panel’s query returns data. For large migrations, use provisioning with Git to manage changes.

Can I automate the migration of data source UIDs in JSON?

Yes. You can write a script that reads the JSON, replaces the uid fields in the datasource objects, and then imports via the API. This is a common practice for multi-tenant migrations.

Related

• Smartwatch vs Smart Ring: Which Should You Buy?
• Drone Simulators vs Indoor Whoops vs Gimbals
• Word Show Hide Paste Options: How to Turn It Off