What you will be able to do
- Explain how dbt retry uses run_results.json to decide which nodes to re-execute
- Predict what dbt retry does after a successful run, an unfixed failure, a fixed failure and an early connection failure
- Narrow or adjust a retry with --select, --exclude, --selector, --target and --vars
- Rerun an errored dbt platform job from the point of failure and say which steps it re-invokes
Key concept
dbt retry — A command that reads the results of the last invocation and re-executes only the nodes that errored or were skipped. Upstream nodes that already succeeded are not rebuilt.
1.What dbt retry re-executes, and how it knows
A nightly dbt build that fails on model 180 of 200 should not have to rebuild the 179 models that already succeeded. dbt retry exists for this case. It runs the previous command again from the point of failure and rebuilds only the nodes that errored or were skipped. dbt v1.6 introduced it, together with dbt clone, as a way to support mature deployments at scale.
Retry decides where to start from a file, not from memory. It reads run_results.json, the artifact the previous invocation wrote, to see which nodes passed and which did not. That makes retry a form of working with dbt state: the record of the last run picks the next selection, much as a saved manifest drives [state selection](lesson:7.1). Retry needs no selector from you because the earlier results already carry one.
Two consequences follow, and both come up on exams. When the previous command succeeded, there is nothing to resume, so retry ends without doing anything and prints Nothing to do. When you retry without fixing the cause, the same nodes fail in the same way. The documentation calls this result idempotent: retry repeats the attempt but does not change its outcome.
The same mechanism works below the model level. A [microbatch model](lesson:1.14) processes its data as independent batches. If some of those batches fail, dbt retry reprocesses only the failed batches, not the whole backfill window.
Checkpoint 1 of 8· Check yourself
Your dbt run finished with every model passing. A colleague runs dbt retry straight afterwards. What happens?
Retry resumes from failures it finds in run_results.json. A fully successful run leaves none, so retry ends as a no-op.
“If the previously executed command completed successfully, retry will finish as no operation.”Source: docs.getdbt.com
Checkpoint 2 of 8· Exam question
A CI job runs `dbt build` against a project with five models. The `stg_customers`, `stg_orders`, and `stg_payments` views build successfully, the `customers` table model fails with a SQL parser error, and the `orders` table model finishes successfully. A teammate pushes a fix for the parser error to the same branch. Which command lets the pipeline resume without rebuilding the three staging views or the `orders` model that already succeeded?
Correct answer: A — Run `dbt retry`, which reads the run_results.json from the failed invocation and re-executes only the customers model that errored out.
- A. dbt retry reads run_results.json from the prior invocation to identify exactly which node errored, then resumes from that point without rebuilding nodes that already succeeded. This is the mechanism designed for exactly this recovery scenario.
- B. A full-refresh build reprocesses the selected models from scratch and is not scoped to just the failure; it does not consult the prior run's failure record, so the already-successful staging views would rebuild needlessly.
- C. Running build again from a clean invocation recompiles the entire DAG and reprocesses every node in dependency order, which is precisely the redundant rebuild the team wants to avoid.
- D. Cloning points a model at another environment's relation instead of fixing and rebuilding it locally, so it does not apply the corrected SQL that was just pushed.
2.Reading the log of a retried run
Take a five-model DuckDB project. Three staging views build cleanly. Then the customers table fails with a typo, selct instead of select, and orders succeeds.
4 of 5 START sql table model main.customers .................................... [RUN]
5 of 5 START sql table model main.orders ....................................... [RUN]
4 of 5 ERROR creating sql table model main.customers ........................... [ERROR in 0.03s]
5 of 5 OK created sql table model main.orders .................................. [OK in 0.04s]Concurrency: 24 threads (target='dev')
1 of 1 START sql table model main.customers .................................... [RUN]
1 of 1 ERROR creating sql table model main.customers ........................... [ERROR in 0.03s]
Done. PASS=4 WARN=0 ERROR=1 SKIP=0 TOTAL=5Look at the counters as well as the node lines. The unfixed retry attempts 1 of 1, yet its summary still reads PASS=4 ... ERROR=1 ... TOTAL=5, the same totals as the original run. After the typo is fixed, the next retry starts customers alone once more, reports OK created sql table model main.customers, and ends with PASS=1 WARN=0 ERROR=0 SKIP=0 TOTAL=1. In each case the staging views are left alone. Retry does not rebuild the upstream models a failed node depends on.
Checkpoint 3 of 8· Check yourself
After the typo in customers is fixed, dbt retry is run. Which nodes does it build?
Retry resumes at the node that errored. The staging views and orders already succeeded, so the fixed retry builds customers alone and reports TOTAL=1.
“In each scenario dbt retry picks up from the error rather than running all of the upstream dependencies again.”Source: docs.getdbt.com
Sources1
3.Early failures and the commands retry supports
Retry can only resume work that was recorded. Suppose a job fails before any node runs, for example because the warehouse rejects the connection or the role lacks a permission. Then run_results.json lists no nodes, and retry has nothing to start from. It runs nothing, even though the job clearly failed. The fix is manual: check run_results.json to confirm that nothing executed, then run the full job again. Once that run has built some nodes, retry works again from any new point of failure.
Retry also works only with commands that produce node results it can resume. The supported commands are:
- build, run, test, seed and snapshot
- compile, clone and docs generate
- check and run-operation
If a run failed in any of these, dbt retry re-invokes the same command for the unfinished nodes. You never have to name the command, because retry repeats the one that ran last.
Checkpoint 4 of 8· Match them up
Match each situation to what dbt retry does next
Tap a term, then the definition that fits it.
Retry acts only on failed or skipped nodes recorded in run_results.json. With none recorded, there is nothing to resume, and an unfixed node simply fails again.
“retry won't run anything since there are no recorded nodes to retry from.”Source: docs.getdbt.com
Checkpoint 5 of 8· Exam question
The nightly `dbt build` job completes with zero errors and zero skipped nodes. A few minutes later, an engineer runs `dbt retry` against that same target without making any code changes. What happens?
Correct answer: A — dbt retry reports that there is nothing to do, since the previous invocation already completed successfully and no failed nodes were recorded.
- A. When the previous invocation finished with no failures, dbt retry has no failed nodes to resume from and reports that there is nothing to do rather than taking any build action.
- B. dbt retry does not blindly rerun the whole DAG; it only resumes nodes recorded as failed or skipped, so a fully successful prior run gives it nothing to reprocess.
- C. dbt retry does not error out when there are no failures to resume; a clean prior run simply results in a no-op rather than a fatal error.
- D. dbt retry resumes from the prior invocation's own failure record; it does not switch to state comparison or pick up a state:modified selection on its own.
Sources1
4.Adjusting a retry with flags and selectors
By default retry repeats the last invocation as it was, but you can change where and how it runs. In a self-hosted dbt installation or the Studio IDE, retry accepts the usual connection and path flags. That lets you point a retry at a different target, profile or variable set without rebuilding the selection yourself.
| Flag | Input value | What it sets | Example |
|---|---|---|---|
| -t, --target | target | The target to execute | dbt retry -t prod |
| --profile | profile | The profile to use | dbt retry --profile jaffle_shop |
| --profiles-dir | path | The directory to load the profiles from | dbt retry --profiles-dir ~/.dbt |
| --target-path | path | The output directory for all produced assets | dbt retry --target-path target |
| --vars | vars | Variables for the project | dbt retry --vars '{"my_var": "new_value"}' |
Selection is where dbt v1 and v2 differ. In v1, a retry inherits the previous run's selection. In v2, you can pass --select, --exclude or --selector to retry, and these override the inherited selection set. Use this when a failure touched many nodes and you want to resume only one branch first, such as a single model and its children.
dbt retry --select my_model+The dbt platform CLI is stricter. Running against a cloud environment, retry accepts only a small set of overrides, typically --threads, --vars and related options. The exact list depends on your CLI build, so run dbt retry --help to see it.
Checkpoint 6 of 8· Fill the gap
Which flag completes this dbt v2 retry, which skips one package and limits the retry to a named selector?
dbt retry --exclude package:analytics ? nightly_models--selector names a selector defined in the project, here nightly_models. Together with --exclude, it overrides the selection the retry would otherwise inherit.
Source: docs.getdbt.comSources1
5.Rerunning a failed job from the point of failure in the dbt platform
Scheduled jobs in the dbt platform offer the same resume behavior through a button. A job can be rerun from failure only when all of these are true:
- The environment uses dbt version 1.6 or newer - dbt can parse the project and generate a manifest - The latest status of the job's most recent run is Error - The failed command is one that supports the retry command
The parsing condition matters in practice. If the error is a broken project that cannot be parsed, fix that first, because the rerun needs a manifest.
| Option | What runs | When it fits |
|---|---|---|
| Rerun from start | The whole job from its first step | No nodes were recorded, for example after a connection or permission failure |
| Rerun from failure | The failed step and any skipped steps, listed in the Rerun failed steps modal | Some steps succeeded and you have committed a fix for the one that failed |
A rerun from failure tells you that it resumed. The new run's Run Summary tab shows a banner reading "This run resumed execution from last failed step". This lets anyone reviewing Run History tell a resumed run from a fresh one.
Checkpoint 7 of 8· Put it in order
Put the steps for rerunning an errored job from failure in order
- 1.Make the fix, then save and commit it to your Git repo
- 2.Review the failed and skipped steps in the Rerun failed steps modal and confirm
- 3.Open Deploy, then Run History, and choose the job run that errored
- 4.On the job's Run page, click Rerun and choose Rerun from failure
- 5.In the Run Summary tab, expand the failed step marked with ❌ and read the error
You find and diagnose the failure first and commit the fix before rerunning. The modal then confirms which steps will be re-invoked.
“After you have made your changes, save and commit them to your Git repo.”Source: docs.getdbt.com
Checkpoint 8 of 8· Exam question
An engineer is troubleshooting a failed self-hosted `dbt build` run and wants to narrow the scope of the next `dbt retry` invocation. Which of the following overrides does `dbt retry` accept for this purpose?(Select 3)
Correct answers: A, B, C — `--select`, which lets you narrow the retry to a subset of the originally failed nodes instead of rerunning the full prior selection.; `--exclude`, which removes specific nodes from the retry scope so they are skipped even though the prior invocation reported them as failed.; `--vars`, which lets you pass different project variable values into the retry invocation than the ones used in the original failed run.
- A. dbt retry supports an optional select override that narrows the resumed scope to a subset of the previously failed nodes instead of inheriting the entire prior selection.
- B. An exclude override is also accepted by retry, letting specific failed nodes be left out of the resumed run even though the prior invocation recorded them as errors.
- C. The vars flag is listed among retry's supported overrides, so a different set of project variable values can be supplied for the resumed invocation.
- D. Full-refresh is not part of retry's documented override list; retry is designed to resume a prior failure, not to force a truncate-and-rebuild of incremental logic.
- E. Defer is a node-selection concept used with commands like run or build to resolve unselected refs against another environment; it is not among retry's supported overrides.
- F. A state flag for comparing against a saved manifest is part of state-based node selection, not part of the documented set of flags that dbt retry accepts.
Sources4
Exam traps
Each one states something that sounds right. Open it to see what is actually true.
1.If a job fails on a warehouse connection error, dbt retry rebuilds everything that did not run.Why is that wrong?
When no node executed before the failure, run_results.json has nothing to resume from, so retry runs nothing. Rerun the full job manually.
2.Retrying a failed model also rebuilds the upstream models it depends on.Why is that wrong?
Retry resumes at the failed node. Upstream models that already succeeded are not run again.
Covered in Reading the log of a retried run
3.Rerun from failure in the dbt platform re-invokes only the step that failed.Why is that wrong?
It re-invokes the failed step and every step that was skipped because of it. The Rerun failed steps modal lists them all.
Covered in Rerunning a failed job from the point of failure in the dbt platform
4.The dbt platform CLI accepts every flag that dbt retry takes in a self-hosted installation.Why is that wrong?
Against a cloud environment, retry accepts only a small subset of overrides, typically --threads and --vars. dbt retry --help lists what your build supports.
Covered in Adjusting a retry with flags and selectors
Sources
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.https://docs.getdbt.com/reference/commands/retryOfficial docs
“Retry references run_results.json to determine where to start. Executing retry without correcting the previous failures yields idempotent results.”
↩︎ What dbt retry re-executes, and how it knows“In each scenario dbt retry picks up from the error rather than running all of the upstream dependencies again.”
↩︎ Reading the log of a retried run“we recommend checking your run_results.json file and manually re-running the full job so the nodes build.”
↩︎ Early failures and the commands retry supports“Once some nodes have run, you can use retry to re-execute from any new point of failure.”
↩︎ Early failures and the commands retry supports“Those arguments override the prior invocation’s selection set for the retry run instead of only inheriting it.”
↩︎ Adjusting a retry with flags and selectors“The dbt retry flags apply when you use a self-hosted dbt installation or the Studio IDE.”
↩︎ Adjusting a retry with flags and selectors“Retry re-executes the last invocation from the point of failure.”
↩︎ Key concept“retry won't run anything since there are no recorded nodes to retry from.”
↩︎ Exam trap 1“In each scenario dbt retry picks up from the error rather than running all of the upstream dependencies again.”
↩︎ Exam trap 2“dbt retry accepts only a small subset of overrides”
↩︎ Exam trap 4“If the previously executed command completed successfully, retry will finish as no operation.”
↩︎ Checkpoint“1 of 1 START sql table model main.customers”
↩︎ Prediction“retry won't run anything since there are no recorded nodes to retry from.”
↩︎ Checkpoint - 2.https://docs.getdbt.com/docs/dbt-versions/dbt-upgrade/Older%20versions/upgrading-to-v1.6Official docs
“Rebuild just the nodes that errored or skipped in a previous run/build/test, rather than starting over from scratch.”
↩︎ What dbt retry re-executes, and how it knows - 3.
“If one or more of your batches fail, you can use dbt retry to reprocess only the failed batches.”
↩︎ What dbt retry re-executes, and how it knows - 4.https://docs.getdbt.com/docs/deploy/retry-jobsOfficial docs
“If your dbt job run completed with a status of Error, you can rerun it from start or from the point of failure in dbt.”
↩︎ Rerunning a failed job from the point of failure in the dbt platform“The job command that failed in the run must be one that supports the retry command.”
↩︎ Rerunning a failed job from the point of failure in the dbt platform“The modal lists the run steps that will be invoked: the failed step and any skipped steps.”
↩︎ Exam trap 3“After you have made your changes, save and commit them to your Git repo.”
↩︎ Checkpoint