--- title: Errors description: The publish finding envelope and its layers, every semantic check code, the refresh failure classes, and the named refusals you will meet. updated: 2026-08-05 --- Dashies refuses in three different places, and which one you hit tells you what to do about it. | Where | When | What survives | |---|---|---| | **Publish** | Before anything is written | Nothing was published. Fix and republish. | | **Refresh** | On a schedule, unattended | The last good body stays live. The run is recorded as failed. | | **The published page** | While a reader is looking at it | The tile states a reason in place. See [Honest degradation](/reference/tiles#honest-degradation). | ## The publish finding envelope A failed publish reports every finding at once, in a fixed shape: ```text Publish failed - 2 errors (nothing was published): - [semantic] /datasets/revenue/measures/arr: measure `arr` divides one aggregate by another ... - [compile] /tiles/3/measure: a pie cannot display a "cents"/"points"-scaled measure ... ``` Warnings use a separate line and do not stop the publish: ```text warning: [compile] /datasets/revenue/sql: ... ``` The bracketed word is the **layer**, and the path is a JSON pointer into your spec. | Layer | What it means | |---|---| | `arg` | A tool argument is wrong: the path, the metadata, a `spec_edits` entry. | | `identity` | The document does not name the dashboard you are publishing to: a slug mismatch, or a `look.from` that does not resolve. | | `steer` | The dataset mode could not be resolved and you have to declare it. | | `semantic` | The spec is well-formed but the seeded data contradicts what it declares. | | `compile` | The spec cannot be turned into a page, or the page is over the publish cap. | | `seed` | A dataset's SQL did not run, or did not return the whole result. | | `conflict` | The stored spec moved under you. Re-read and re-apply. | | `write` | The bytes or the row could not be stored. | | `internal` | A bug on our side. Nothing was published; please report it. | **At most ten semantic findings are reported per publish**, errors first. When more exist, a `findings_truncated` entry says how many of which severity were cut. Fix what is listed and re-run to see the rest. ## Semantic checks These run against the **seeded data**, not just the spec, which is why they can catch a declaration the data contradicts. An `error` blocks the publish; a `warning` does not. | Code | Severity | What it caught | |---|---|---| | `col_missing` | error | A declared dimension or measure has no matching output column. | | `col_extra` | error | An undeclared output column would ship as public island bytes. Declare it or drop it from the query. | | `type_not_numeric` | error | A measure needs a numeric column and its output column is not one. | | `agg_mismatch` | error | The measure declares one aggregate and the query computes another. | | `count_not_integer` | error | A `count` measure seeded non-integer values, so it is really an average. | | `predivided_ratio` | error | A measure divides one aggregate by another in SQL. That re-sums wrong under viewer filters. Declare a `ratio` measure instead. | | `hybrid_rows_missing_column` | error | A `hybrid` measure's source column is absent from `rows_sql`, so the row-level path cannot recompute it. | | `lattice_no_grand_total` | error | The lattice has no all-rolled-up cell, so the unfiltered dashboard boots blank. | | `seed_empty` | error | The dataset seeded zero rows, so nothing it declares can be verified. | | `seed_truncated` | error | The island holds fewer rows than the dataset really has. The missing cells would refresh silently wrong. | | `seed_probe_unavailable` | error | The completeness probe returned no count, so there is no evidence the island is whole. | | `rate_shaped_sum` | warning | A `sum` over values all between 0 and 1. Summing rates is usually wrong. | | `percent_points_suspect` | warning | A measure declared `percent`/`fraction` seeded values that look like 0 to 100. | | `date_dim_not_iso` | warning | A date dimension seeded non-ISO values. Bucket to `YYYY`, `YYYY-MM` or `YYYY-MM-DD` in SQL. | | `domain_drift_at_publish` | warning | A seeded value falls outside its declared `domains`, so the runtime filter will drop it. | | `series_cardinality` | warning | More distinct series values than the five-colour mark palette. | | `slice_cardinality` | warning | More distinct slices than a pie or donut will draw. | | `funnel_stage_absent` | warning | A declared funnel stage matches no seeded value, so it renders as absent. | | `stack_percent_mixed_sign` | warning | A `stack: percent` column seeds both positive and negative segments, so its shares would be no true proportion. | | `manual_cross_check` | advisory | A dataset is built over more than one row source. | :::danger{title="`manual_cross_check` is the one no static check can close"} A join that matches more than one row per key **silently multiplies every additive measure**, and nothing in the pipeline can see it. Two things make it worse than it sounds: On a `lattice` or `hybrid`, each cell is still the exact aggregate of the duplicated rows, so every subtotal reconciles with every total and the dashboard looks internally consistent. Checking it against itself finds nothing. Measured at roughly 150 times inflation on a real star schema. A `rows` dataset does not escape it by deferring the aggregation: the duplicated rows are already baked into the published island, and the query engine then aggregates them correctly and returns the inflated number. The only thing that finds it is a comparison against an independent direct aggregate: [Verify your numbers](/guides/verify-your-numbers). ::: ## Named publish refusals | Code | What happened | |---|---| | `over_publish_cap` | The compiled body is over the publish limit. The message names the byte count and the heaviest dataset. | | `spec_conflict` | The stored spec changed since you read it. Re-read with `get_dashboard_spec` and re-apply. | | `spec_base_stale` | Your `base_spec_hash` no longer names the stored spec: it was republished after you read it. | | `spec_ref_unknown` | A `spec_hash` names neither the stored spec nor a document still held server-side. Send the document. | | `spec_too_large` | The result of applying `spec_edits` is over the spec byte limit. | | `slug_mismatch` | The spec's `slug` differs from the publish path. The path is the target; rename with `update_dashboard`. | | `look_from_no_body` | `look: { from }` points at a dashboard with no published body to inherit. | | `look_from_mismatch` | `look: { from }` must equal the publish target slug. To reuse another dashboard's body, read it and inline it. | | `custom_html_script` | A `