Troubleshooting

Errores de contexto de root, billing o workspace

Síntomas

El CLI reporta root inválido, workspace faltante, o mismatch de path.

Secuencia de fix

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

Corre los comandos de billing desde <local_root> y los comandos de workspace desde el root del workspace.

La validación falla antes del push

Síntomas

looky validate reporta issues de model, visualization o dashboard.

Orden de fix

1. Arregla primero los issues de alias de source / runtime config.
2. Arregla las definiciones de queries de model y los nombres.
3. Arregla las referencias query y mapping de visualization.
4. Arregla las referencias de items y filtros de dashboard.
5. Re-corre looky validate hasta que no queden errores bloqueantes.

El push tuvo éxito pero el dashboard está mal o falta

Síntomas

El dashboard no es visible, está vacío, o es inconsistente con el output esperado en my.looky.studio.

Secuencia de fix

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

Después recarga la UI. Si el dashboard sigue fallando, confirma que los ids de visualization referenciados en el YAML del dashboard matcheen exacto los ids de visualization publicados.

Mismatch de source/runtime

Síntomas

Los models no pueden resolver tablas o el comportamiento del data source difiere inesperadamente.

Secuencia de fix

looky sources diff
looky sources list
looky validate

Asegúrate que los aliases usados en los models matcheen exacto los aliases definidos en runtime/sources.runtime.yml.

Recuperarse de un push malo

El disaster recovery es responsabilidad del caller. El camino forward más sano es arreglar el archivo localmente y volver a pushear. Para volver a un estado previo, necesitas ese estado en tu laptop — mantén el workspace en git, o apóyate en el snapshot local .bk/<timestamp>/ que looky pull escribe dentro de tu workspace local cada vez que sobrescribe un archivo.

El .bk/ local son archivos planos al lado de tu workspace — cópialos de vuelta al lugar correspondiente y corre looky push para restaurar ese estado en el server.

Leyendo códigos de error de validación

Cada error o warning de validación lleva un prefix de código estable. El prefix te dice qué gate se disparó y a qué familia de archivos concierne:

• WS*** — issues en workspace.yml (fields faltantes, shape de identifier, referencia de billing-account).
• RT*** — issues en runtime/sources.runtime.yml (tipo de source faltante o no soportado, credentials_file faltante, dsn faltante para postgres/mysql, archivo de credenciales no encontrado en secrets/ en disco). Frecuentemente warnings en vez de errores bloqueantes.
• MD*** — issues en archivos de model (alias de source desconocido, archivo de model fuera de content/, archivo no legible).
• VZ*** — issues estructurales del YAML de visualization (campos requeridos faltantes, referencia de query malformada, id duplicado). VZ020 y VZ021 específicamente flagean propiedades chart.* que violan el schema tipado para el viz type.
• DB*** — issues del YAML de dashboard (layout_mode fuera de fluid_grid / document, referencias a visualizations desconocidas, ids duplicados).
• EX*** — issues del YAML de export (formato cron, referencia a dashboard desconocido, ids duplicados).
• MR*** — errores levantados por el server al correr la validación contra el runtime live:
  • MR000 — falló cargar visualizations / dashboards / sources.
  • MR001 — error de compile / parse / sintaxis de Malloy, o cualquier otra falla aparecida por el query engine. La línea que sigue al código empieza con Malloy service HTTP <status>: y lleva el error específico del engine. Mira "Mensajes de error de engine bajo MR001" abajo para los comunes.
  • MR002 — nombre de field o query referenciado en una query no está definido en el source Malloy.
  • MR003 — el model referencia un alias de source desconocido.
  • MR004 — la introspección de schema falló (no puede leer schema para una relación).
  • MR005 — query engine inalcanzable.
  • MR006 — query engine timeouteó — parte el workspace si es inusualmente grande.
  • MR008 — archivo de model faltante o fuera de content/.
  • MR009 — falla genérica de precheck.
  • MR010 — source inalcanzable desde la probe de conectividad (chequea que looky push --settings corrió con credentials actuales).

Los códigos locales (WS / RT / MD / VZ / DB / EX) vienen del chequeo local que corre el CLI antes de contactar al server. Los códigos server (MR* y VZ020 / VZ021 emitidos por el server) vienen de la validación corrida contra el runtime live. Mira Publish para el flujo completo.

Mensajes de error de engine bajo MR001

MR001 reporta cualquier cosa que el query-engine rechaza, con prefix Malloy service HTTP <status>:. El mensaje trailing identifica la causa específica y apunta al fix:

• HTTP 400 — unsupported_model_shape — al model le falta el shape estricto que cada model de Looky necesita: el pragma ##! experimental.parameters arriba del archivo, más paréntesis en la declaración del source (source: name() is …, incluso cuando el source no toma parámetros). Agrega los dos y re-valida. Mira Models.
• HTTP 400 — unbound_param — el model usa un placeholder @param en SQL crudo que no tiene declaración matcheante en la signature del source. El error nombra el parámetro faltante; declaralo dentro de los paréntesis del source, ej. p_date_from::date is null. Tipos comunes: date, string, number, boolean.
• HTTP 400 — missing_sources_config — este workspace todavía no tiene settings publicados. Corre looky push --settings una vez y valida de nuevo. Mira Publish.
• HTTP 400 — malformed_request — el CLI mandó un request body inválido al server. Esto es un bug de CLI, no un issue de model. Reintenta; si persiste, comparte el request id con tu administrador.
• HTTP 500 — una falla inesperada en la plataforma o en tu data source (errores de BigQuery / Postgres / MySQL, timeouts). Chequea el request id, reintenta, y escala si persiste.