Skip to content

Reference

Errors

The publish finding envelope and its layers, every semantic check code, the refresh failure classes, and the named refusals you will meet.

Dashies refuses in three different places, and which one you hit tells you what to do about it.

WhereWhenWhat survives
PublishBefore anything is writtenNothing was published. Fix and republish.
RefreshOn a schedule, unattendedEach dataset keeps the data from its own last successful refresh. The run is recorded as failed.
The published pageWhile a reader is looking at itThe tile states a reason in place. See Honest degradation.

The publish finding envelope

A failed publish reports every finding at once, in a fixed shape:

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:

warning: [compile] /datasets/revenue/sql: ...

On a publish that succeeds, warnings arrive grouped rather than one line each: warnings to review first, then the checks you owe, then routine notes. The same warning on several datasets prints once, with a Same for datasets: line naming the rest. A dataset whose data stays with Dashies gets one note in place of the separate warnings about it (two on a page of managed tiles, three on a page whose markup you wrote), and a publish whose First data: line says its rows are already served drops the wait from that note, which leaves no note at all on a page of managed tiles. A publish that passes a dry run's spec_hash and report_id counts the warnings that dry run printed or counted, on a line that opens Since the dry run of, instead of printing them again; the publish_dashboard reference says when that applies. The JSON part of the response always lists every warning.

The bracketed word is the layer, and the path is a JSON pointer into your spec.

LayerWhat it means
argA tool argument is wrong: the path, the metadata, a spec_edits entry.
identityThe document does not name the dashboard you are publishing to: a slug mismatch, or a look.from that does not resolve.
steerThe dataset mode could not be resolved and you have to declare it.
semanticThe spec is well-formed but the seeded data contradicts what it declares.
compileThe spec cannot be turned into a page, or the page is over the publish cap.
entitlement_gateA dataset declares an entitlement block that cannot be published as written. See Row-level security.
seedA dataset's SQL did not run, or did not return the whole result.
conflictThe stored spec moved under you. Re-read and re-apply.
writeThe bytes or the row could not be stored.
internalA 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.

CodeSeverityWhat it caught
col_missingerrorA declared dimension or measure has no matching output column.
col_extraerrorAn undeclared output column would ship as public island bytes. Declare it or drop it from the query.
type_not_numericerrorA measure needs a numeric column and its output column is not one. A min or max over a DATE or TIMESTAMP column is the exception: it publishes on a dataset Dashies keeps the data for (a warehouse or an uploaded file), except on SQL Server, whose publish cannot read a column's type, and on a Snowflake TIMESTAMP_LTZ or TIMESTAMP_TZ column, which reaches the publish as text until it is cast; it is refused with a sentence about dates everywhere else.
agg_mismatcherrorThe measure declares one aggregate and the query computes another.
count_not_integererrorA count measure seeded non-integer values, so it is really an average.
predivided_ratioerrorA measure divides one aggregate by another in SQL. That re-sums wrong under viewer filters. Declare a ratio measure instead.
hybrid_rows_missing_columnerrorA hybrid measure's source column is absent from rows_sql, so the row-level path cannot recompute it.
lattice_no_grand_totalerrorThe lattice has no all-rolled-up cell, so the unfiltered dashboard boots blank.
seed_emptyerrorThe dataset seeded zero rows, so nothing it declares can be verified.
seed_truncatederrorThe island holds fewer rows than the dataset really has. The missing cells would refresh silently wrong.
seed_probe_unavailableerrorThe completeness probe returned no count, so there is no evidence the island is whole.
rate_shaped_sumwarningA sum over values all between 0 and 1. Summing rates is usually wrong.
percent_points_suspectwarningA measure declared percent/fraction seeded values that look like 0 to 100.
date_dim_not_isowarningA date dimension seeded non-ISO values. Bucket to YYYY, YYYY-MM or YYYY-MM-DD in SQL.
date_dim_timestamperrorA type: date dimension whose column is a timestamp, or whose seeded values carry a time of day. The page keys a date dimension by its day, so each day would split by time and a day filter would match only its midnight rows. Cast it to a date in SQL; the hint names the cast for your engine (CAST(col AS DATE) on most, TRUNC(col) on Oracle, and on BigQuery DATE(col), or DATE(col, '<zone>') for a TIMESTAMP truncated in a time zone, since a bare DATE reads its day in UTC).
date_dim_numericerrorA type: date dimension whose column is a number, such as an integer year. A date dimension reads a number as milliseconds since 1970, so it would show as 1970-01-01. Drop type: date, or build a date in SQL.
timestamp_dim_has_timeerrorA dimension NOT declared a date whose column is a timestamp with times of day. The page keys a timestamp dimension by its day whatever it is declared, so it has the same two defects as date_dim_timestamp. Cast it to a date in SQL for days, or format it as text for hours. A timestamp whose rows are all at midnight is not refused. Not yet detected on SQL Server, or on Snowflake TIMESTAMP_LTZ / TIMESTAMP_TZ columns, where the publish sees the column as text.
domain_drift_at_publishwarningA seeded value falls outside its declared domains. Widgets list it after the declared members, but the publish sized the dataset from the declared members alone, so it is larger than it was checked at.
series_cardinalitywarningMore distinct series values than the five-colour mark palette.
slice_cardinalitywarningMore distinct slices than a pie or donut will draw.
funnel_stage_absentwarningA declared funnel stage matches no seeded value, so it renders as absent.
stack_percent_mixed_signwarningA stack: percent column seeds both positive and negative segments, so its shares would be no true proportion.
declared_grain_over_cell_boundwarningA grain your page asks a served dataset for can exceed the query service's cell bound, so that grain would be refused. Each grain is priced on its own, because the service answers each as its own question and refuses each on its own, so the other grains of the same dataset keep answering. The message names which dashies.data call asks for it, the grain, the estimate, the bound and the widest dimension, once per grain that is over; ask for a narrower grain with by in that call, bound the dimensions with domains or buckets, or declare fewer. A grain asked with sort and limit is priced at its cut, so a top 10 of 12,000 is ten rows; one asked with no limit answers every member and is priced as the whole grain. Estimated from the declared domains, the seed and your page's own subscriptions, on a dry run as on a publish. A dataset no call asks for is not estimated.
manual_cross_checkadvisoryA dataset is built over more than one row source.

`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.

Named publish refusals

CodeWhat happened
over_publish_capThe compiled body is over the publish limit. The message names the byte count and the heaviest dataset.
spec_conflictThe stored spec changed since you read it. Re-read with get_dashboard_spec and re-apply.
spec_base_staleYour base_spec_hash no longer names the stored spec: it was republished after you read it.
spec_ref_unknownA spec_hash names neither the stored spec nor a document still held server-side. Send the document.
spec_too_largeThe result of applying spec_edits is over the spec byte limit.
slug_mismatchThe spec's slug differs from the publish path. The path is the target; rename with update_dashboard.
look_from_no_bodylook: { from } points at a dashboard with no published body to inherit.
look_from_mismatchlook: { from } must equal the publish target slug. To reuse another dashboard's body, read it and inline it.
custom_html_scriptA <script> in a custom tile's html is inert. Move runtime code to the tile's js.
browser_parquet_unavailableA dataset asks for its rows as a Parquet file the viewer's browser reads (mode: rows with data: { mode: parquet }), and a published dashboard cannot load that file's reader from outside Dashies. Delete the data: { mode: parquet } line; the default keeps the rows in the page. This lasts until Dashies serves the Parquet reader itself.
page_markup_egressThe page's markup reaches off Dashies in a way the sandbox cannot stop: a <script type="speculationrules"> block, or a <link rel="prefetch" / "prerender" / "preconnect" / "dns-prefetch" / "modulepreload" pointing at a non-Dashies host, read as the browser resolves its address. The browser would prefetch or connect to that host before anyone asks, so publish refuses it, inside a <template> too: a declarative shadow root's template is live before any script runs, and any other is a clone away from the page. Remove it, or point the link at a Dashies origin.
page_script_computesThe page's own script shows a number it worked out: arithmetic, toFixed, toLocaleString or Intl.NumberFormat on a delivered value, a largest or smallest value or where it sits, a count of the rows however it was kept (rows.length, a counter, a reduce), or a row's position; a measure as it arrived rather than through dashies.format (String(v), or a value whose field publish cannot tell apart from a measure), or a value a row carries handed to dashies.format with the dataset in place of its measure entry; or a value worked out from a delivered one and the viewer's clock, a random draw or the browser ("3 years ago"). Or it writes into the rows it was handed. Text drawn on a canvas, the document's title, and an attribute a reader sees (title, aria-label, alt, value) are shown too, and so is aria-valuenow (with aria-valuemin and aria-valuemax), which a screen reader reads out as a bare number: put the value's dashies.format text in aria-valuetext, which it reads instead. Show a delivered value through dashies.format(value, measure), a dataset's count through dashies.format(ds.members, ds), show a date as its day, and declare a measure or a ratio in the spec for a total, a difference or a share. The message quotes the code and gives its line.
page_script_comparesThe page's own script shows text or a value a test on a number chose, or writes text under one: a word such as "High", a sign, a unit or any other glyph (whitespace alone aside) picked by a threshold (revenue > 500 ? 'High' : 'Low') or written under if (revenue > 500), a formatted value or a label drawn, cleared or kept only under such a test, by a number's truth (v ? 'changed' : 'flat', `v
page_script_orders_rowsThe page's own script sorts or reverses the rows it was handed, or a copy of them, walks them backwards, places values by a number (out[v] = ...), or orders two delivered category values against each other (a.month < b.month, localeCompare), which is how a page ranks rows without sorting. Dashies delivers every grain in a fixed order, by value unless a dimension's domains declares one, so the earliest and the latest are the first row and the last; ask for another order with sort on dashies.data (sort: 'revenue:desc'), and a table or chart widget sorts itself with data-sort.
page_script_chooses_rowsThe page's own script cuts the rows it was handed, or a copy of them (slice with arguments, splice, pop, shift), reads one row by a position other than the first or the last (rows[2]), stops a loop over them short of their count or steps over some, or decides which rows it draws by something other than a category value: a number (r.revenue > 500, in a filter or in the if a return or continue runs under), a row's position or a counter against a bound it sets (i < 5) where it decides whether a row is drawn (a skip, a filter, or an if, a ternary or && around a delivered value's draw; laying out or styling by it, such as a two-line legend or the first rows styled, is fine), a random draw or the viewer's clock, or a function publish cannot read (window.keep(r)). A category value, or anything worked out from one alone (a prefix, a length, a date's month), picks rows freely. Ask for a top N with sort and limit on dashies.data, and for the members meeting a threshold with having there (having: [{ key: 'aov', op: '>', value: 500 }]); a table or chart widget shows a top N with data-sort and data-limit, and dashies.filter narrows what every subscription is handed. A position Dashies delivered (r.__rank_pos) picks rows no more than the page's own does: it is shown and styles freely, and a pick by it is a top N by position. To leave a label off a bar too short to hold it, draw the row, write the label's text unconditionally and hide it with a class the test toggles (el.classList.toggle('is-hidden', h < 14)), rather than skipping the row. A type test (typeof v === 'number', Number.isFinite(v), Number.isNaN(v)) picks rows as a null test does.
page_script_escapeThe page runs code publish cannot read: eval, new Function, a constructor called to build code, Reflect, with, a string handed to a timer, markup parsed from a string (DOMParser, createContextualFragment, setHTMLUnsafe, setHTML, Document.parseHTMLUnsafe, Document.parseHTML, execCommand('insertHTML'), document.write and writeln: a dashboard needs none of them; build the elements, or set innerHTML or insertAdjacentHTML, which publish reads), a created script or frame, an event handler or a javascript: URL set from text, a frame, embed or srcdoc in the markup (inside a <template> too, since a page can clone one in), another frame's window (contentWindow, frames, opener), a global read or written through a computed name, a worker, or a read of any script element's text: the data block by its id or type, document.scripts, getElementsByTagName('script'), or a selector naming a script. Write the code itself, and take numbers only from dashies.data. A function of your own that shares a name with one of these parsers (setHTML or parseHTML, say) is refused too, so rename it: publish refuses DOMParser, parseFromString, createContextualFragment, setHTMLUnsafe, setHTML, parseHTMLUnsafe and parseHTML by name, whatever object they are called on, and execCommand the same way when its command is insertHTML or not a literal string. A library inlined into the page can meet this: it uses Reflect and the rest where a dashboard needs none.
page_webrtc_egressThe page's own script names RTCPeerConnection. A peer connection leaves the page over UDP, outside everything the dashboard's network lock controls, so publish refuses it. A dashboard needs none.
page_hint_egressThe page's own script sets a <link>'s rel to a resource hint (preconnect, dns-prefetch, prefetch, prerender, preload or modulepreload), writes one into markup it builds, or sets a rel from a value it builds. A hint opens a connection or a fetch the page never makes as a request, and a preconnect or a prerender leaves even under the dashboard's network lock, so publish refuses it. A dashboard needs no hint: set rel as a literal that names none. A page published since this refusal also refuses one in the browser, so a hint a script builds where publish cannot read it throws a TypeError naming it instead. That covers the routes listed here: a rel set through the rel property, relList, setAttribute or an attribute node; markup handed to innerHTML, outerHTML, insertAdjacentHTML, setHTMLUnsafe, setHTML, createContextualFragment, Document.parseHTMLUnsafe, a DOMParser, document.write or execCommand('insertHTML'); and a <template>'s content read while it holds one. That browser check is best-effort defense in depth: it covers the listed routes, and whether they are all the routes a page has was not independently reviewed. Publish's refusals are the reviewed layer. A <link> your markup carries cannot be pointed at another address once it names a hint, and a speculation-rules <script> is refused the same way. It runs before your own scripts, and what it checks with is fixed before they run. Your scripts can still wrap or replace a DOM method as they could without it, and it adds about 7.5 KB to the page and about 1 ms to building 20,000 elements (measured in Chrome).
null_leading_dimensionA dimension's leading value is null.
timezone_bucketThe SQL buckets time without naming a zone, or with an ambiguous single AT TIME ZONE. Not raised when the warehouse reports every value a bucket reads as a DATE taken from a DATE column.
page_network_callNot a refusal: the page's own script calls the network (fetch, XMLHttpRequest, WebSocket, and the like). A published dashboard reaches only Dashies, so a request to a third-party origin is refused in the viewer's browser and returns nothing. Read data through dashies.data(callback), declare a logo under assets (Dashies fetches and verifies it), and embed a font as a data: URI. The message names the surface and the calls it found.
multi_series_controlsNot a refusal: a chart in your page draws several series (data-measures or data-series) and carries data-controls. A multi-series chart draws no sort or limit controls, so a reader gets none. Remove data-controls from it, or chart a single measure if the reader needs to reorder it or change how many members it shows.
page_script_uncheckedNot a refusal: publish could not finish reading the page's own script for the checks above, and says so rather than reporting a clean result. The page publishes. Please report it.
parquet_pendingNot a failure: a dataset whose rows are kept outside the page publishes with no data until a refresh reads them. On a page of managed tiles those tiles read "Updating"; on a page whose markup you wrote, your own dashies.data callback is handed status: "pending" for that wait, so draw a "no data yet" state for it. The human report says this once per dataset, in one note that also stands for parquet_pending_manifest and, on a page whose markup you wrote, author_renderer_served_dataset, and it drops the wait from that note when the publish's First data: line says the rows are already served.
entitlement_requires_enterpriseA dataset declares an entitlement block, and row-level security is an Enterprise capability. One code, two sentences: the usual one says this workspace is not on the Enterprise plan and points at the plan page; the other says Dashies could not read this space's plan, so the publish was refused rather than admitted. On that one, publish again. check_readiness answers whether it is available in a space before you write the block.
entitlement_requires_served_modeA dataset declares an entitlement block and is not on the served path. The filter is applied where the data is queried rather than in the page, so the dataset has to declare mode: resolved.
entitlement_not_supported_on_engineA dataset declares an entitlement block and this dashboard's data source cannot have a per-viewer filter enforced on it yet. One code, two sentences: the message either names the data source and the ones that do work, or says Dashies could not establish which data source the connection is. Upgrading a plan does not change the first case.
entitlement_root_without_datasetA dashboard-level entitlement block with no dataset-level one. The dashboard-level block carries only the admin opt-out, so on its own it opts out of a filter that does not exist. Declare the entitlement on the dataset whose rows it should filter, or remove the dashboard-level block.
entitlement_removal_undeclaredThe dashboard you are publishing over filters its rows per viewer today, and this document declares no entitlement block, so publishing it would serve every row to every viewer. To remove the filter on purpose, set row_level_security_removed: true at the top level of the document; to keep it, restore the dataset's entitlement block. One code, two sentences: the other says Dashies could not read whether the dashboard filters, so the publish was refused rather than admitted. On that one, publish again rather than declaring the removal, which would unfilter a dashboard nobody has established filters.
entitlement_removal_contradictedThe document declares an entitlement block AND row_level_security_removed: true, which cannot both be true of one dashboard. Remove the removal declaration to keep filtering, or remove the entitlement block to stop.
expr_not_plain_expressionA measure declares a SQL expression that is not a plain expression: it carries a subquery, a relation reference, a table function or a semicolon. The expression is evaluated over a scratch relation holding only the viewer's own rows, so a subquery, a relation reference or a table function is refused here rather than failing later. The message names the measure and the word. If the word is a column name, quote it. extract, substring and trim are the only functions whose from separator is accepted; date_part, year, substr and the two-argument trim spell the same thing without one. The check is per DASHBOARD, not per dataset: a dashboard where any dataset declares an entitlement block has every expression measure checked, and a dashboard that declares no entitlement block anywhere is not checked at all.
compiler_invariant, internal_errorA bug on our side. Nothing was published; please report it.

Refresh failure classes

A scheduled refresh that fails records one class on the run. A dataset whose data did not refresh keeps the data it had.

ClassRecorded messageWhat to do
connection_authwarehouse connection authentication failedThe credential is wrong or revoked. If the data source signs in with a password or key, enter the new one on the data source in the web app. A BigQuery data source that signs in without a key has none: its Google Cloud setup is what refused it, so check the provider and the Workload Identity User grant there. On Snowflake, the subcode unload_to_stage_prevented is a setting rather than a credential: PREVENT_UNLOAD_TO_INTERNAL_STAGES is on for the Dashies user, and the app's explanation of the failed refresh names the ALTER USER statement that allows it (Connect Snowflake).
connection_unreachablewarehouse was unreachableNetwork, firewall, or a paused warehouse.
connection_timeoutwarehouse query timed outThe cube is too slow for the refresh budget. Narrow it.
ssl_failedwarehouse TLS/SSL negotiation failedA TLS problem at the warehouse.
schema_driftwarehouse schema changed; cube query no longer matchesA table or column was renamed or dropped, the query asks for a name it does not return, or the login can no longer read the object, which Snowflake reports the same way. Fix the SQL, or restore the login's access. On a PostgreSQL data source not added as only accepting known IP addresses, press Resync schema first, so the schema your AI tool reads from Dashies is current.
cube_errorwarehouse cube query failedEverything else the query raised.
tier_lapsedthe plan that pays for this dashboard's refresh has lapsed; paused until it is upgradedNot a failure of the query. It resumes on upgrade.
connection_removeddata connection is no longer activeThe connection was deleted or disabled. Dependent dashboards were paused.
extractor_hostthe Dashies extraction service failed; this is ours, not your warehouseThe refresh failed inside Dashies, not at your warehouse. Nothing in the connection or the cube needs changing. Read the recorded reason for which part failed. One exception is known: on Snowflake, a network rule that protects the account's internal stages refuses the download a refresh needs, and that is recorded under this class today (Connect Snowflake).
audit_refuseda dataset's new data did not pass its checks against the version it would replace, so the refresh published nothing for that dataset, which keeps what it served beforeIt depends on the check. Some find something only you can clear, such as a dataset that came back with no rows where it had many, and the alert about one says what to do. The others need nothing from you. When the fault is ours says which of these comparisons is which. The refused dataset keeps what it served before, and other datasets of the same refresh may still have updated. Read the recorded reason for which check refused.

Only three of those are evidence the connection itself is unhealthy: connection_auth, ssl_failed and connection_unreachable. The rest are about one dashboard's query, which is why a connection can read active while one of its dashboards keeps failing.

audit_refused also carries a refusal that is not a check on new data. A refresh of only the access rules (scope: "grants") that reaches a dataset which has not been refreshed yet is refused as first_refresh_required: that dataset had served nothing, so there were no access rules in force to replace. Refresh the dashboard's data once; that reads the access rules as it goes, and a refresh of the access rules alone works from then on.

`connection_timeout` is deliberately not a connection-health signal

A timeout means a slow cube on a healthy warehouse. Counting it would flip a connection to failing because one dashboard grew too big, and take every other dashboard on that connection with it.

Never the raw driver text: the executor drops the message and the detail before the class is recorded, because they carry the remote host, user, database and port.

Authentication failures

A request to the web app carrying an unusable session cookie returns 401 {"ok":false,"error":"unauthenticated (<reason>)"}. The reason is a stable machine token, mainly for log analysis:

ReasonMeaning
no_cookieNo session cookie was sent.
malformedThe cookie or its token could not be parsed.
expiredThe token is past its expiry.
invalid_signatureThe signature did not verify.
wrong_issuerThe token was issued by something else.
wrong_audienceThe audience claim does not match: for example an anon key used as a session.
no_subThe token carries no subject.
fetch_failedThe signing keys could not be fetched. Transient.

Any of these means sign in again. An MCP tool never surfaces these: the client re-runs the browser flow on its own. See the authorization flow.

Check it worked

Publish with dry_run: true first. It runs the whole pipeline, seed included, and writes nothing, so every finding above is reachable without creating a dashboard. A clean dry run and a failing real publish differ only in the write layer.