Use this page to look up any error string you see in an embed, the metric builder, or a guest-token API response.
Embed runtime errors
These surface when an embedded dashboard or metric loads. Guest tokens are database-backed UUIDs, not signed JWTs — there is no signing key, so none of these errors are about signatures.
| Error | Meaning | Fix |
|---|
INVALID_TOKEN | The token UUID was not found in the deployment being queried | Check for a cloud vs self-hosted mismatch (a token exists only in the environment that minted it); confirm the embed receives the exact minted value; mint a fresh token |
TOKEN_EXPIRED | The token exists but its expiryTime has passed | Mint a fresh token; refresh cached tokens before the deadline. Tokens without expiryTime never expire |
UNAUTHORIZED_ORIGIN | The page’s origin is not on the Whitelist Domains list | Add the origin (scheme-less host[:port], wildcards like *.example.com supported) under your Data App’s settings → Whitelist Domains. Whitelist your domain, not api.usedatabrain.com. The list is account-wide |
UNAUTHORIZED | The token is not allowed this request. On dashboard load: the ID isn’t in the token’s params.allowedEmbeds, or the dashboard doesn’t belong to the token’s Data App/workspace. On dashboard-filter or dashboard-view requests: that capability isn’t granted | For load errors: fix allowedEmbeds or the ID. For filter/view errors: enable End User Dashboard Filter / Create Dashboard View in the Data App’s Access Control, or grant it in the token (params.accessPermissions.isAllowEndUserDashboardFilter, permissions.isEnableCreateDashboardView) |
INVALID_ID | The dashboard/embed ID does not belong to the token’s Data App | Verify the ID and that the token was minted for the right Data App |
UNAUTHORISED REQUEST! | The request is missing a valid plugin token header | Ensure the embed component receives a token attribute |
Metric execution errors (E1001–E1007)
| Code | Message | Cause & fix |
|---|
E1001 | Filter or Client variables detected in the query. | The final SQL still contains an unresolved {{…}} token at execution. Causes: variable name doesn’t match the filter’s variable name (case-sensitive); the filter has no value or default; no matching filter is attached. Fix the name and give the filter a default value. See Filter Troubleshooting |
E1002 | Metric data or query could not be found. | The metric’s stored query is missing — re-save the metric |
E1003 | Drill-down query execution failed. | The drill-down query errored — check the underlying SQL |
E1004 | Invalid query or insufficient permissions to access it. | The query failed validation or the caller lacks access |
E1005 | An error occurred while fetching data from the database. | The data source returned an error — test the connection and run the SQL directly against the source |
E1006 | Forecast query execution failed. | The forecast service errored on this metric |
E1007 | Hasura server error occurred while processing the request. | Internal metadata-layer error — on self-hosted check the hasura service; on cloud contact support |
Multi-select filter variables substitute as a parenthesized quoted list (e.g. ( 'US' , 'CA' )). Write WHERE col IN {{var}} without your own parentheses — IN ({{var}}) double-wraps into invalid SQL.
Guest-token API errors (mint time)
Returned by POST /api/v2/guest-token/create. See the Guest Token reference for the accepted payload.
| Code | Meaning |
|---|
AUTHENTICATION_ERROR | Invalid or missing API key in the Authorization header |
INVALID_REQUEST_BODY | The body failed validation — includes any unknown field (dataAppId, client_id, tenant_id, permissions.dashboards are not valid fields) |
INVALID_DATA_APP_NAME | dataAppName doesn’t match any Data App (case-sensitive) |
CLIENT_ID_ERROR | Invalid clientId value |
WORKSPACE_ID_ERROR | Workspace not found or inaccessible |
DASHBOARD_PARAM_ERROR / EMBED_PARAM_ERROR | Invalid dashboard/embed parameters |
APP_FILTER_PARAM_ERROR | Invalid params.appFilters shape |
RLS_SETTINGS_PARAM_ERROR | Invalid params.rlsSettings shape |
DATASOURCE_NAME_ERROR / DATAMART_NAME_ERROR | datasourceName / datamartName doesn’t resolve |
UNSUBSCRIBED_ACCOUNT_ERROR | The account’s subscription doesn’t allow this operation |
INTERNAL_SERVER_ERROR | Server-side failure — retry, then contact support |
Browser-side errors
QuotaExceededError … 'metric-data' exceeded the quota
The embed plugin caches metric data in localStorage, and a large metric blew past the browser’s per-origin quota (~5–10 MB).
- Clear the key:
window.localStorage.removeItem('metric-data') and reload.
- Reduce the row/column count of the offending metric (
LIMIT, pagination, or split it).
This is a browser storage limit — it is unrelated to API rate limits, and the self-hosted RATE_LIMIT env var has no effect on it.
Rate limiting (HTTP 429)
Cloud API requests are throttled per Data App. Back off using the Retry-After header and cache read-heavy calls. See Rate Limiting. 
