drt-debug
/drt-debug
Debug and fix a failing drt sync. Use this skill whenever a user reports errors running drt, asks why a sync is failing, or needs to diagnose drt configuration problems (auth errors, rate limits, template errors, etc.).
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.
Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.
What it does and when to use it
Debug and fix a failing drt sync. Use this skill whenever a user reports errors running drt, asks why a sync is failing, or needs to diagnose drt configuration problems (auth errors, rate limits, template errors, etc.).
Original author description
Debug and fix a failing drt sync. Use this skill whenever a user reports errors running drt, asks why a sync is failing, or needs to diagnose drt configuration problems (auth errors, rate limits, template errors, etc.).
How it works
- Steps
- Common Error Patterns
- Tools to escalate to
- Telemetry
- Reference
SKILL.md preview
---
name: drt-debug
description: >
Debug and fix a failing drt sync. Use this skill whenever a user reports
errors running drt, asks why a sync is failing, or needs to diagnose
drt configuration problems (auth errors, rate limits, template errors, etc.).
---
Debug a failing drt sync.
## Steps
1. Start with the environment-level triage:
```bash
drt doctor # checks env vars, profile file, python/extras, common gotchas (v0.7+)
```
This catches the bulk of "it doesn't even start" cases before you read code.
2. If `drt doctor` is clean, ask the user to share (or read from context):
- The error output from `drt run` or `drt status`
- The sync YAML (`syncs/<name>.yml`)
- The `drt_project.yml` if relevant
3. Reproduce with more signal — pick the right verbosity:
- `drt run --select <name> --verbose` — row-level error details
- `drt run --select <name> --dry-run` — config parses, no data sent
- `drt run --select <name> --dry-run --diff` — record-level preview for queryable destinations. It distinguishes omitted fields from explicit nulls: partial updates preserve them, replace shows `<default>`, and append-only writes show INSERT (#1138)
- `drt run --output json` / `drt status --output json` — structured output for CI / scripting (v0.7+)
- `drt run --log-format json` — JSON Lines logs to stderr (separate from `--output`)
- `drt run --select <name> --limit 10` — really load ≤10 rows (#774) to reproduce with a small, inspectable send; cursor watermarks and snapshot-diff baselines do not advance (refused for `mode: mirror` / `replace`)
- `drt run --failed` — re-run only the syncs whose last status wasn't `success` (#773) — the tight loop while fixing one red sync in a larger project
- `drt run --fail-fast` — stop after the first failure (#775) instead of running the whole set when the cause is systemic
4. Diagnose the root cause using the patterns below.
5. Suggest a concrete fix with the corrected YAML or command.
## Common Error Patterns
### Auth errors (401, 403)
- **Cause**: `token_env` or `value_env` env var not set, or token has wrong permissions.
- **Fix**: Check `echo $MY_TOKEN`, verify token scopes. For HubSpot, confirm Private App has CRM write scope. For GitHub, confirm `actions: write`.
- **Provider URI**: an `*_env` value beginning `aws-sm://`, `gcp-sm://`, or `vault://` is a secret-provider URI, not an env-var name. Install its matching extra, then use `drt doctor` to distinguish a missing provider dependency from an IAM/path error.
- **Hardcoded-secret detection (v0.7.5+)**: if `drt validate` flags `hardcoded secret detected`, the YAML literally contains a token instead of `token_env`. Move it to an env var and reference it.
### Rate limit (429)
- **Cause**: Sending too fast for the destination's limits.
- **Fix**: Lower `sync.rate_limit.requests_per_second`. HubSpot max: 9 req/s. GitHub Actions: 5 req/s.
- **Also**: Add retry config — 429 is retryable by default; in v0.7+ you can also set a per-destination retry override.
- **Recover the rows that still failed**: enable the dead letter queue (`sync.dlq.enabled: true` + `on_error: skip`, v0.7.9+) so per-record failures persist to `.drt/dlq/<sync>.jsonl` instead of being dropped, then `drt retry <sync>` re-sends just those once the limit clears. `drt status` shows the queue depth.
- **Staged Upload**: when one vendor quota spans multiple hosts, or separate accounts share one host, set `destination.rate_limit_key` to the real stable quota identity; this public YAML field overrides the host-derived key (`rate_limit_key_override` is internal, not YAML).
### Connection errors / timeouts
- **Cause**: Wrong URL, network issue, or destination is down.
- **Fix**: Verify `url` with `curl -X POST <url>` manually. `drt run --dry-run` confirms config parses correctly without sending traffic.
- **On the source side (#766, v0.8.4+)**: transient extract failures are already retried automatically (3 attempts, exponential backoff) — a Snowflake `390114` token expiry, a Databricks warehouse cold start, a Postgres connection reset, a 5xx on a REST page. No config needed. ⚠️ Retries cover **connection + query execution only**; a failure after the first row was yielded is *not* retried (those rows are already loaded and can't be un-sent), so a mid-read drop still fails the sync. Auth failures are never retried — repeated attempts can trip an account lockout, so a persistent connect error is more likely a credential/permission problem than a flaky network.
### Template errors
- **Cause**: `{{ row.field_name }}` references a column that doesn't exist in the source.
- **Fix**: `drt run --dry-run` previews rows; confirm column names match the template. For `datetime` / `Decimal` / `UUID` columns flowing into a REST API `body_template`, use the `tojson_safe` filter (v0.7.6+) rather than `CAST(... AS STRING)` in SQL.
### Engine-stage attribution (v0.7.6+)
- **Cause**: `ErrorFormatter` now attaches a stage tag to every error (`extract` / `load` / `finalize` / `validate`). If the surfaced error mentions a stage you didn't expect (e.g. a `finalize` failure on a SQL destination's mirror mode), the bug is in that stage's code path — not in the load loop.
- **Fix**: Stage tag narrows the search. For `finalize` failures on `sync.mode: mirror` (v0.7.7+), check `upsert_key` is set and the source key cardinality is small enough to hold in memory.
### Incremental sync not filtering
- **Cursor strategy cause**: `mode: incremental` has no saved cursor yet, so the first run syncs all rows.
- **Cursor fix**: Check `drt status` after the first run — `last_cursor_value` should be set. To probe a backfill boundary, use `drt run --cursor-value '<value>' --select <name>`.
- **Snapshot-diff strategy**: `incremental_strategy: diff` deliberately reads the full model into a warehouse snapshot, then emits only added/changed rows. It requires `mode: upsert|mirror`, a destination `upsert_key`, no `cursor_field`, and a Postgres/Snowflake/Databricks/BigQuery source profile with writable `managed_schema`. A first run has no prior baseline, so every row is added. Same-sync overlapping runs are unsupported. `--limit` does not promote the baseline.
### Poisoned or stuck watermark
- **Cause**: a bad cursor value got persisted (a timezone bug, a bad backfill, a rebuilt source table), so the sync now filters out rows it should send — or sends nothing at all.
- **Diagnose**: `drt state show <name>` — shows the stored watermark, last status and row count. Works for remote watermark backends (GCS / BigQuery) too, which `.drt/*.json` inspection does not.
- **Fix**: `drt run --select <name> --full-refresh` re-reads everything and persists a fresh watermark (v0.8.4+). Prefer this over hand-editing `.drt/watermarks.json`, which does nothing when a remote backend is configured.
- **Note**: `--cursor-value` is a *probe* — it overrides one run and leaves stored state untouched. `--full-refresh` is the reset.
- **Not included**: `--full-refresh` does not reset tracked-mirror state. If mirror deletes look wrong, that is `drt state reset <name> --tracked-mirror` — read its warning first, since re-baselining makes rows written by other systems into deletion candidates.
### `on_error: fail` stopping early
- **Cause**: Default behavior for some destinations — first failure stops the sync.
- **Fix**: Change to `on_error: skip` to continue past failures and see the full error count via `drt run --verbose` or `drt status`.
- **Recover the failures**: pair `on_error: skip` with `sync.dlq.enabled: true` (v0.7.9+) so the skipped records land in `.drt/dlq/<sync>.jsonl`; `drt retry <sync>` replays just them after you fix the root cause. To re-run whole syncs that failed (not individual records), use `drt run --failed` (#773). See `docs/guides/dead-letter-queue.md`.
### Profile not found
- **Cause**: `~/.drt/profiles.yml` missing or profile name mismatch.
- **Fix**: `cat ~/.drt/profiles.yml`, verify the profile name matches `drt_project.yml`. Override per-run with `drt run --profile <name>` or the `DRT_PROFILE` env var.
### SQL destinations: qualified-identifier errors (`schema.table`)
- **Cause**: Older versions mis-quoted `schema.table` as a single identifier — e.g. ClickHouse `Code: 62` on `db.table`, Postgres syntax errors on `marketing.events`.
- **Fix**: Already fixed in v0.7.3 (Postgres `_quote_ident` #498), v0.7.4 (MySQL #514), v0.7.8 (ClickHouse #610). Upgrade to the latest patch release and the qualified form parses correctly.
### Snowflake mirror mode: MERGE-only write path
- **Cause**: `sync.mode: mirror` forces the MERGE write path regardless of `config.mode` (v0.7.7+).
- **Fix**: This is intentional. Don't rely on `replace` semantics for Snowflake mirror — Snowflake's mirror doesn't have a swap path.
### Managed-schema permission failures
- **Cause**: `incremental_strategy: diff` or `state.backend: warehouse` needs drt-owned tables under the connection profile's `managed_schema` (default `_drt`), but the role cannot create/probe/write them.
- **Fix**: Grant the connector guide's managed-schema permissions, or have an administrator pre-create the schema and feature tables and grant only the documented table privileges. `managed_schema` is on the Postgres/Snowflake/Databricks/BigQuery profile, not under `sync.diff` or project `state`.
### Google Sheets `column mismatch`
- **Cause**: Sheets is positional: the first batch fixes the column order from the union of keys it sees, and a later batch introduced a new field.
- **Fix**: Make records structurally consistent or raise `sync.batch_size` so every sparse field appears in the first batch. Missing values for already-known columns are written as empty cells.
### Slack / webhook delivery failed (silent)
- **Cause**: Webhook URL returned 4xx but the upstream sync still succeeded; you missed it.
- **Fix**: Configure the sync's `alerts.on_failure` channels — Slack / webhook notifications fire when the run hits a hard failure.
### `Change guards tripped` (v1.2)
- **Cause**: `sync.guards` (`max_deletes` / `max_delete_pct`, plus `max_creates` / `max_updates_pct` in `drt plan` / `drt apply`) refused a run that would change more rows than allowed. This is the guard working, not a bug. For a plain trip nothing was deleted or swapped; the two variants below say otherwise, so read the full message.
- **Fix**: first ask *why* the number is larger than usual (empty or partial source, a changed model, a wrong `mirror.scope`). If the change is genuinely intended, review it with `drt plan`, then `drt apply --force-guards` (a human decision; recorded in the run results), or raise the limit in the YAML. Never add `--force-guards` to an automated job.
- **A percentage trip with no baseline**: `mirror.strategy: diff` reports no denominator, so `max_delete_pct` fails closed — use `max_deletes` there.
- **`...but rollback failed; the destination outcome is uncertain`** (Postgres/MySQL/Snowflake): the guard tripped but the rollback of the refused DELETE failed — check the target table's row count before re-running.
- **`...AFTER the DELETE ran; it is already committed`** (Databricks/BigQuery): these cannot roll a DELETE back. The pre-count passed but the statement removed more than counted (a concurrent writer) or its row count was unreadable. Recover with `RESTORE TABLE ... TO VERSION AS OF` (Delta) or table time travel (BigQuery).
### `drt apply` refuses a plan (v1.2)
- **Cause**: apply recomputes the plan and aborts on any difference (the source or destination changed, or the sync definition changed), if the plan was already applied (a plan is single-use), or if the destination cannot be read back (plan covers SQL databases/warehouses; `update_only` / `create_only` are refused).
- **Fix**: run `drt plan` again and review the new change set. See `docs/guides/plan.md` and the refusal table in the `drt-review-sync` skill.
### `write_policy: fill_empty` rejected at validate (v1.2)
- **Cause**: `fill_empty` needs an upsert write path — it is rejected with `destination.mode: insert` and with `sync.mode: replace` (a rebuilt table has no existing value to keep), and `create_only` has nothing to fill.
- **Fix**: use `mode: merge`/upsert with an `upsert_key`; see `docs/guides/write-policy.md`.
## Tools to escalate to
- `drt test --select <name>` — runs the post-sync validation tests (freshness / unique / accepted_values) declared in the sync YAML; use this when "the sync says success but the data looks wrong".
- `drt_run_test` MCP tool (v0.7.5+) — same as `drt test` but callable from Claude/Cursor without leaving the chat.
- `target/drt/run_results.json` — durable per-invocation results even in text output mode. Raw exception text is intentionally omitted; use console/`--output json` for the full error. A preflight failure before sync selection does not produce the artifact, and `--target-path` relocates it.
- OTel traces (v0.7+, Phase 1+2 shipped) — set `observability.otel.endpoint` in `drt_project.yml` and `pip install drt-core[otel]` to capture spans. Phase 3 engine spans (`drt.sync.run` / `drt.sync.extract` / `drt.sync.load`) shipped v0.7.10 (`pip install drt-core[otel]`).
## Telemetry
drt ships anonymous opt-in telemetry (PostHog Cloud EU, off by default, v0.7.2+). If a user is debugging in an offline / regulated environment and wants to be sure no analytics fire, set `DO_NOT_TRACK=1` or `telemetry.enabled: false` in `~/.drt/config.yml`. drt also honours the `DO_NOT_TRACK` standard env var with no config.
## Reference
- `docs/llm/CONTEXT.md` for architecture and key concepts.
- `docs/llm/API_REFERENCE.md` for all config fields.
- `docs/connectors/` for per-connector details (auth, sync modes, gotchas).
Versions
The database has no other skills named drt-debug.
Database snapshot: 13.11.2026 · package version 3b2f2e43f640 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100drt-create-sync
Generate a drt sync YAML configuration file. Use this skill whenever a user wants to create a new drt sync, connect a data warehouse table to an external service, or set up a Reverse ETL pipeline with drt. - 100drt-init
Guide a user through initializing a new drt project. Use this skill when a user is setting up drt for the first time, asks how to get started with drt, or needs help configuring their data warehouse connection. - 100speak-common-errors
Diagnose and fix common Speak API errors: authentication failures, audio format issues, rate limits, and session management problems. Use when implementing common errors features, or troubleshooting Speak language learning integration issues. Trigger with phrases like "speak… - 100clickhouse-common-errors
Diagnose and fix the top 15 ClickHouse errors — query failures, insert problems, memory limits, and merge issues. Use when a ClickHouse query or insert throws an exception, a server-side error appears in logs, or a failed query needs root-cause analysis. Trigger with "clickhouse… - 90troubleshooting
Diagnose pipeline issues, failed events, schema validation errors, and enrichment problems. Use when users report missing events, validation failures, or pipeline errors. Use this skill whenever events appear to be missing, dropping, or failing, even if the user just says… - 100gamma-common-errors
Debug and resolve common Gamma API errors. Use when encountering authentication failures, rate limits, generation errors, or unexpected API responses. Trigger with phrases like "gamma error", "gamma not working", "gamma API error", "gamma debug", "gamma troubleshoot".