How to fix a broken dashboard: step-by-step troubleshooting
A broken dashboard can grind your reporting to a halt—right when you need quick insights. Whether you’re dealing with missing data, failed visualizations, or outdated charts, debugging dashboards can be stressful.
This guide walks you through how to diagnose and fix broken dashboards by identifying issues in your data pipeline, queries, or infrastructure.
What causes a broken dashboard?
Most dashboard issues boil down to one of three core problem areas. Understanding where your broken dashboard originates will help you fix it faster:
-
Input Issues (Broken data sources). A dashboard may break when the data feeding it has changed. Maybe a column was renamed, a file format shifted, or a source system went offline.
-
Transformation Failures (Broken logic). Dashboards built on transformed data can break when the underlying logic changes—think SQL updates, dbt model edits, or broken joins.
-
Operational Errors (Broken nfrastructure). Even if your data and queries are solid, the dashboard can still fail due to job scheduling issues, permission changes, network disruptions, or infrastructure downtime.
How to troubleshoot a broken dashboard
Step 1: Trace the problem to the source
A broken dashboard is often a symptom of deeper data issues. Start by tracing the data flow backward—from the dashboard to the raw data source.
If you use a data lineage tool, this is the perfect time to open it. Look for the earliest upstream node that’s producing unexpected or empty results. The closer you can get to the origin of the data breakage, the faster you can fix it.
Sometimes it’s just one failed transformation; sometimes, you’ll need to backfill multiple broken tables.
Step 2: Check for broken query logic
Once you’ve identified the suspect table or transformation, it’s time to investigate the logic that powers it:
🔍 Review recent query edits: Was the SQL changed recently?
🧠 Check assumptions: Could new filters, joins, or aggregations be excluding key data?
Many broken dashboards result from queries that technically run—but return incomplete or misleading data. Always validate both the logic and the output.
Step 3: Examine the data directly
If the logic looks fine, dive into the data itself. Broken dashboards often stem from subtle issues like:
📆 Gaps in time periods (e.g., missing weeks or months).
⏰ Timezone mismatches in timestamps.
💱 Incorrect currency formats or conversions.
📊 New or missing segments, like devices or domains.
🔢 Formatting issues, like text in numeric fields.
These data issues can quietly erode trust in your dashboard if left unnoticed.
Step 4: Audit the operational environment
Still stuck? Your broken dashboard might not be a data or logic issue—it could be operational. Common culprits include:
⏳ Delayed data syncs between ETL tools and databases.
🔒 Changed permissions that restrict access to tables or dashboards.
⚙️ Failed scheduled jobs or broken cron tasks.
🧵 Network or connectivity issues.
📦 Recent infrastructure changes, like cloud migrations or resource limits.
Your Metabase logs and job monitoring tools should help you pinpoint where things went sideways.
Solving a broken dashboard doesn’t need to be a mystery—just follow the data breadcrumbs and stay methodical. For more help, check out Metabase’s troubleshooting guide.