Skip to main content
This walkthrough covers the most common runtime failure: a source schema changed underneath the generated models. A column the warehouse models depend on is dropped from a raw table, the next scheduled refresh fails, and the operator recovers with an assistant repair.

​
1. The failure appears in Monitoring

The scheduled refresh runs dbt against raw tables that no longer match the models, so the run fails. Monitoring’s Issues section keeps the unresolved failure visible. Open Runs, select the Failed or dbt filter, and expand the run to read its events and logs. If a notification channel is configured (Slack webhook, generic webhook, or email), a failed-refresh notification also fires, naming the failing step and environment — for example “dbt run failed in prod” — with the run summary as detail.

​
2. Schema drift names the cause

Platinur keeps a baseline of the raw source schemas as they existed when the first build generated the models. An hourly runtime health check compares the current source schemas against that baseline, and Monitoring has a Check button to run the comparison on demand. The Monitoring schema drift strip shows one of:
  • Drift detected — “Schema drift — N change(s) in raw schemas since the last build”, with an expandable list of changes.
  • Clean — “Schema drift — raw schemas match the last build”.
  • No baseline — the baseline is captured by the first build.
Each drift event names the exact change, for example:
  • column_removed — “schema.table lost column X.”
  • column_type_changed — “schema.table.X changed type from A to B.”
  • table_removed — “schema.table no longer exists.”
  • column_added / table_added — new columns or tables since the last build.
A dropped source column shows up as a column_removed event. Schema drift remains visible in Monitoring. The current notification preferences cover dbt-run and integration failures; they do not promise a separate schema-drift notification.

​
3. Start an assistant repair from the failed run

Repairs run in Staging. Production is release-only, so switch to Staging if needed — on a production failure the run card shows the repair button disabled with that reminder. Open the failed run card in Monitoring and click Repair with Assistant. Platinur queues a “Repair failed dbt run” task and opens it in the Assistant view. The button only appears on failed runs, and repair attempts are limited (default 2, configurable as Attempt Limit in Configuration). If the limit is reached or the same validation error repeats, the repair is blocked with “Escalate with logs.”

​
4. What the repair agent does

The repair agent never edits the live workspace. It works in a sandbox copy of the generated code on the worker, under .platinur/agent-runs/<task id>/.
  1. It starts by reading the failed run’s logs, then inspects the failed model SQL and YAML, their ref() dependencies, upstream models, and model contracts. It can run bounded read-only warehouse queries to confirm which columns actually exist — it does not guess.
  2. It writes complete replacement files, restricted to the generated dbt models and Evidence dashboard paths. It cannot touch secrets, configuration, users, or infrastructure.
  3. It validates the fix by running dbt for the failed selector, tests included by default. If validation fails, it inspects the new logs and retries within the attempt limit.
  4. It commits the fix to Staging only after validation passes. If sandbox files change after the last successful validation, it must validate again before committing.
If the agent cannot fix the failure safely, it stops without changing Staging and explains what blocked it. Failed repair attempts stay in the Assistant activity log. The Assistant view shows concise live activity and a completion card. Detailed changed files, diff, validation, ancestry, and Undo live in Promotions.

​
5. Review the staged repair

The validated repair commit appears in Promotions with the other staged changes:
  1. Review the diff and validation status.
  2. Check the staging model run and dashboard preview.
  3. Undo the change if the result is not right, or include it in a dependency-aware named release. Production syncs from its configured branch after the release merges.
If validation or the staging commit fails, the failure remains visible in the run and Monitoring so you can start another repair with the preserved context.

​
6. Re-run and confirm

Re-run the refresh manually or wait for the next scheduled run, and confirm it succeeds in Monitoring → Runs. The newer success resolves the older failure in Issues. The drift baseline reflects the schemas as of the last build, so Monitoring continues to report the schema change even after the models are repaired. Treat it as a record of how the raw schemas have moved since the models were generated; a rebuild captures a fresh baseline.