Troubleshooting

Root, billing, or workspace context errors

Symptoms

CLI reports invalid root, missing workspace, or path mismatch.

Fix sequence

looky login https://my.looky.studio <local_root>
looky whoami

cd <local_root>
looky billing list
looky billing use <billing_account_id>

cd <local_root>/<billing_account_id>/<workspace_slug>
looky status

Run billing commands from <local_root> and workspace commands from workspace root.

Validation fails before push

Symptoms

looky validate reports model, visualization, or dashboard issues.

Fix order

1. Fix source alias/runtime config issues first.
2. Fix model query definitions and names.
3. Fix visualization query and mapping references.
4. Fix dashboard item references and filters.
5. Re-run looky validate until no blocking errors remain.

Push succeeded but dashboard is wrong or missing

Symptoms

Dashboard not visible, empty, or inconsistent with expected output in my.looky.studio.

Fix sequence

looky status
looky diff
looky push
looky list visualizations
looky list dashboards

Then reload UI. If dashboard still fails, confirm visualization ids referenced in dashboard YAML exactly match published visualization ids.

Source/runtime mismatch

Symptoms

Models cannot resolve tables or data source behavior differs unexpectedly.

Fix sequence

looky sources diff
looky sources list
looky validate

Ensure aliases used in models exactly match aliases defined in runtime/sources.runtime.yml.

Recovering from a bad push

Disaster recovery is the caller's responsibility. The cleanest forward path is to fix the offending file locally and push again. To revert to a prior state, you need that prior state on your laptop — keep the workspace in git, or rely on the local .bk/<timestamp>/ snapshot that looky pull writes inside your local workspace whenever it overwrites a file.

The local .bk/ is plain files sitting next to your workspace — copy them back into place and run looky push to restore that state on the server.

Reading validation error codes

Every validation error or warning carries a stable code prefix. The prefix tells you which gate fired and which file family it concerns:

• WS*** — issues in workspace.yml (missing fields, identifier shape, billing-account reference).
• RT*** — issues in runtime/sources.runtime.yml (source type missing or unsupported, missing credentials_file, missing dsn for postgres/mysql, credentials file not found on disk under secrets/). Often warnings rather than blocking errors.
• MD*** — issues in model files (unknown source alias, model file outside content/, file unreadable).
• VZ*** — visualization YAML structural issues (missing required fields, malformed query reference, duplicate id). VZ020 and VZ021 specifically flag chart.* properties that violate the typed schema for the viz type.
• DB*** — dashboard YAML issues (layout_mode outside fluid_grid / document, references to unknown visualizations, duplicate ids).
• EX*** — export YAML issues (cron format, unknown dashboard reference, duplicate ids).
• MR*** — errors raised by the server when running validation against the live runtime:
  • MR000 — failed to load visualizations / dashboards / sources.
  • MR001 — Malloy compile / parse / syntax error, or any other failure surfaced by the query engine. The line that follows the code starts with Malloy service HTTP <status>: and carries the engine's specific error. See "Engine error messages under MR001" below for the common ones.
  • MR002 — field or query name referenced in a query is not defined in the Malloy source.
  • MR003 — model references an unknown source alias.
  • MR004 — schema introspection failed (cannot read schema for relation).
  • MR005 — query engine unreachable.
  • MR006 — query engine timed out — split the workspace if it is unusually large.
  • MR008 — model file missing or outside content/.
  • MR009 — generic precheck failure.
  • MR010 — source unreachable from the connectivity probe (check looky push --settings ran with current credentials).

Local codes (WS / RT / MD / VZ / DB / EX) come from the local check the CLI runs before contacting the server. Server codes (MR* and VZ020 / VZ021 emitted by the server) come from the validation run against the live runtime. See Publish for the full flow.

Engine error messages under MR001

MR001 reports anything the query-engine refuses, prefixed with Malloy service HTTP <status>:. The trailing message identifies the specific cause and points at the fix:

• HTTP 400 — unsupported_model_shape — the model is missing the strict shape every Looky model needs: the ##! experimental.parameters pragma at the top of the file, plus parentheses on the source declaration (source: name() is …, even when the source takes no parameters). Add both and re-validate. See Models.
• HTTP 400 — unbound_param — the model uses a raw-SQL @param placeholder that has no matching declaration on the source signature. The error names the missing parameter; declare it inside the source parentheses, e.g. p_date_from::date is null. Common types: date, string, number, boolean.
• HTTP 400 — missing_sources_config — this workspace has no published settings yet. Run looky push --settings once and validate again. See Publish.
• HTTP 400 — malformed_request — the CLI sent an invalid request body to the server. This is a CLI bug, not a model issue. Retry; if it persists, share the request id with your administrator.
• HTTP 500 — an unexpected failure on the platform or your data source (BigQuery / Postgres / MySQL errors, timeouts). Check the request id, retry, and escalate if it persists.