Skip to main content

Troubleshooting

The shortlist of things that bite people most often, and how to fix each one.

Installation​

ERROR: extension "wal2delta" is not available​

LakeTS is pure SQL — it does not require wal2delta to install. You only need wal2delta if you're enabling Lakebase CDF. If you saw this error during install:

  • Confirm you ran dist/lakets.sql (single-file install) or sql/99_install.sql (from source) and nothing else
  • If you ran a CDF-setup script by mistake, see Lakebase CDF Setup for prerequisites

ERROR: permission denied to create extension​

You need superuser-equivalent privileges in your Lakebase instance. Connect with the database admin role provided in your Databricks workspace, not a read-only role.

ChronoTables​

lakets.create_chronotable() is slow on existing data​

LakeTS has to copy every row from the original table into the new partitioned table. For 100M+ rows, this can take several minutes — the cost is paid once.

To speed it up:

  • Add a temporary index on the time column before calling create_chronotable
  • Run during off-peak hours
  • Or use create_metric_table() from the start so you skip the conversion step

Queries are still scanning every chunk​

Partition pruning only works if your WHERE clause uses the time column in a form Postgres can use. Check for these traps:

  • WHERE time::text LIKE '2026-03%' — string cast, pruning skipped → use time >= '2026-03-01' AND time < '2026-04-01'
  • WHERE date_trunc('day', time) = '2026-03-25' — function on the column, pruning skipped → use time >= '2026-03-25' AND time < '2026-03-26'
  • WHERE time = my_var where my_var is TEXT — implicit cast, pruning may skip → ensure my_var::TIMESTAMPTZ

Confirm with EXPLAIN (ANALYZE) — the plan should list only the chunks you expect.

RollUps​

refresh_rollup() returns FALSE​

The refresh was skipped because not enough time has passed since the last refresh. Check the refresh_lag column in _rollup_registry — by default it's 15 minutes. Lower it for development:

UPDATE lakets._rollup_registry SET refresh_lag = '1 minute' WHERE rollup_name = 'metrics_hourly';

Real-time view returns stale data​

The real-time view is RollUp Table UNION ALL (raw query above watermark). If you forgot to add WHERE time > lakets._rollup_watermark('<rollup_name>') to the raw side, the view will double-count buckets. Re-create with create_rollup_view and confirm the predicate is present.

Dependency cycle detected​

refresh_rollup_cascade performs cycle detection via Kahn's algorithm. If you see this error, two RollUps have circular depends_on references. Inspect with:

SELECT rollup_name, depends_on FROM lakets._rollup_registry;

Break the cycle by dropping one of the dependencies (UPDATE _rollup_registry SET depends_on = '{}').

Lakebase CDF​

_shadow_<table> is empty in Unity Catalog​

CDF only syncs rows that arrive after the shadow table is created. Backfill the existing data manually after enabling sync:

INSERT INTO _shadow_metrics SELECT * FROM metrics;

Then re-enable sync from the Databricks UI.

Schema change broke the sync​

Lakebase CDF is schema-sensitive. After an ALTER TABLE:

  • Stop the sync in the Databricks UI
  • Drop the shadow table and trigger: SELECT lakets.disable_sync('metrics')
  • Re-enable: SELECT lakets.enable_sync('metrics')
  • Re-run the sync setup

wal2delta complains about partitioned tables​

You enabled sync on the ChronoTable itself instead of the shadow table. Make sure _chronotable_registry.sync_enabled = true and the registry's shadow_table_name is what's configured in the Databricks sync — not the partitioned parent.

Performance​

Inserts slow down over time​

Possible causes:

  • Index on a high-cardinality field column — drop it, indexes on tag columns + time are usually enough
  • Too-fine chunk interval — 1 hour partitions create 8,760 chunks per year; switch to 1 day unless you genuinely need hourly drops
  • No retention policy — chunks accumulate forever. Add add_retention_policy() or add_tiered_retention_policy()

Dashboards still slow with a RollUp​

The dashboard might be querying the raw ChronoTable instead of the RollUp Table. Verify the query uses _rollup_<name> or _rollup_rt_<name>, not the base table.

Cardinality alarms​

If cardinality_stats shows a column at >10% of total rows, that column is acting like a primary key. See Manage tag cardinality for fixes.

Where to get help​