菜单
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.).
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
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.
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.
Help migrate from Census, Hightouch, Polytomic, or custom scripts to drt. Use this skill when a user wants to replace their existing Reverse ETL tool with drt, or asks how to replicate a sync they had in another tool.
Walk a drt setup through a full top-to-bottom diagnostic checklist when something is off but the failing layer isn't obvious. Use this when a user says "drt isn't working", a sync silently does nothing, results look wrong, or they want to verify a fresh setup end-to-end — broader than /drt-debug, which fixes a specific known error.
| 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.
Start with the environment-level triage:
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.
If drt doctor is clean, ask the user to share (or read from context):
drt run or drt statussyncs/<name>.yml)drt_project.yml if relevantReproduce with more signal — pick the right verbosity:
drt run --select <name> --verbose — row-level error detailsdrt run --select <name> --dry-run — config parses, no data sentdrt run --select <name> --dry-run --diff — record-level preview (added/updated/deleted) for queryable destinations (v0.7.1+)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; watermark won't 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 projectdrt run --fail-fast — stop after the first failure (#775) instead of running the whole set when the cause is systemicDiagnose the root cause using the patterns below.
Suggest a concrete fix with the corrected YAML or command.
token_env or value_env env var not set, or token has wrong permissions.echo $MY_TOKEN, verify token scopes. For HubSpot, confirm Private App has CRM write scope. For GitHub, confirm actions: write.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.sync.rate_limit.requests_per_second. HubSpot max: 9 req/s. GitHub Actions: 5 req/s.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.url with curl -X POST <url> manually. drt run --dry-run confirms config parses correctly without sending traffic.{{ row.field_name }} references a column that doesn't exist in the source.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.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.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.mode: incremental set but no saved cursor yet (first run syncs all rows).drt status after first run — last_cursor_value should be set. To replay or backfill, use drt run --cursor-value '<value>' --select <name> (v0.6.2+).on_error: fail stopping earlyon_error: skip to continue past failures and see the full error count via drt run --verbose or drt status.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.~/.drt/profiles.yml missing or profile name mismatch.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.schema.table)schema.table as a single identifier — e.g. ClickHouse Code: 62 on db.table, Postgres syntax errors on marketing.events._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.sync.mode: mirror forces the MERGE write path regardless of config.mode (v0.7.7+).replace semantics for Snowflake mirror — Snowflake's mirror doesn't have a swap path.failure_alerts block in drt_project.yml, v0.7.0+ via #414) — Slack / webhook notifications fire when any sync run hits a hard failure.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.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]).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.
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).