Databricks Data Engineer Professional study materials
Databricks Data Engineer Professional study resources

A stream that dies after VACUUM, with a bad deploy waiting to be rolled back

Databricks Data Engineer Professional · Put your knowledge to work in context.

All case studies

A stream that dies after VACUUM, with a bad deploy waiting to be rolled back

At 02:10 a nightly Structured Streaming job fails with A file referenced in the transaction log cannot be found. The stream reads silver.sessions and has been running for 11 days without a restart. A maintenance job runs VACUUM silver.sessions RETAIN 168 HOURS and an OPTIMIZE ... ZORDER nightly; it also vacuums bronze, which a batch job reads for 30-day lookbacks. On-call restarts the stream from the same checkpoint location and it fails again within minutes at the same offset. In parallel, the last deployment - delivered through a Databricks Asset Bundle - changed the streaming trigger from 60s to 10s and doubled worker count, and the tech lead wants to know whether to roll back before or after fixing the failure. Databricks Runtime 15.4 LTS, Unity Catalog managed tables, checkpoint stored in the same storage account.

1. Diagnose the failure and describe the immediate recovery.

Read the worked answer

Diagnosis The error means the Delta transaction log references data files that no longer exist. VACUUM ... RETAIN 168 HOURS keeps seven days; the stream has been running for eleven and pins a snapshot/log version older than that horizon, so VACUUM deleted files that version still needs. Files removed by VACUUM are gone - RESTORE cannot bring them back, because the log entry survives but the underlying objects do not.

That is also why restarting from the same checkpoint fails immediately: the checkpoint resumes at an offset whose source version is already broken, so it re-fails at the same point.

Immediate recovery

  1. Do not disable the retention safety check to vacuum harder, and do not raise retention now - that only prevents the next occurrence.
  2. Start the stream with a new checkpoint location and accept reprocessing of the affected window. Replay is only safe if the sink is idempotent: ensure the write uses a MERGE on a stable key, or Delta idempotent writes with txnAppId/txnVersion per batch.
  3. Reconcile the output for the reprocessed window against bronze to confirm no duplicates were introduced.
  4. Restart downstream consumers so they pick up the corrected data.

2. Set a retention policy that is safe for both the stream and the 30-day batch lookback, and say what else changes.

Read the worked answer

Separate the two risks

  • The batch job reads a single current snapshot and finishes; VACUUM does not delete files belonging to the current version, so a 7-day retention is not inherently unsafe for batch. What breaks is time travel beyond retention, and long-running batch reads that span a vacuum on files they read - check the batch runtime against the maintenance window.
  • The stream is the constraint. Retention must exceed the maximum age of any live reader snapshot, not just the longest job runtime. If streams are restarted only when they fail, that age is unbounded.

Policy Set retention above the longest expected reader lifetime (for example 30 days for high-value silver tables), and enforce operational discipline: restart long-running streams on a fixed cadence (weekly) so no reader outlives the retention horizon. Alert when a stream's uptime approaches the retention window. Keep 7 days only for tables with no streaming readers and no time-travel requirement - the extra storage from longer retention is far cheaper than the outage just experienced.

Also confirm the checkpoint and the table live in storage governed by the same lifecycle policies; an object-lifecycle rule deleting old files has the same effect as an over-aggressive VACUUM and is easy to miss.

3. Should the team roll back the bundle deployment before fixing the failure?

Read the worked answer

No - fix first, then decide whether the deployment is implicated at all. The error is a data-availability problem caused by VACUUM, not by the trigger interval or worker count; rolling back would not make the missing files reappear and would add churn to an incident that is already confused.

That said, the deployment should be handled properly once the pipe is flowing:

  • Bundles are declarative, so rollback means redeploying the previous git commit or tag to the same target, then databricks bundle run to restart the job. Hand-editing the workspace creates drift between the bundle and the deployed state - don't.
  • Changing trigger interval and worker count does not break streaming semantics: the stream can restart with the same checkpoint, provided the query logic itself is unchanged. Changing the query (adding an aggregation, changing the source) requires a new checkpoint.
  • Use repair run for the failed task only; do not rerun already-succeeded tasks that are not idempotent.
  • Add the rollback path to the runbook and rehearse it in a staging target, because 'redeploy the previous commit' is only a fast answer if someone has done it before.