What you will be able to do
- Name the run steps every dbt job includes, both the built-in steps and the commands you configure
- Predict how one failed run step affects the steps after it and the job's final status
- Tell apart a command added to the Commands list and the same command enabled through a checkbox
- Explain what makes dbt run, dbt test, dbt build and selector steps fail
- Find a failed step in the run details and rerun the job from the point of failure
Key concept
Run steps — A dbt job does not run as a single action. It runs as an ordered chain of steps: built-in setup steps followed by each configured dbt command. Every step succeeds or fails on its own, and a failed step stops the chain and gives the job an Error status.
1.What a job run is made of
A dbt job is a collection of run steps, settings and a trigger. It lets the platform invoke dbt commands against your project instead of someone typing them into a terminal or the Studio IDE. The trigger decides when a run starts. The run steps decide what happens once it has started. Most job failures you will debug happen in that second part, which is why it pays to know exactly which steps a run contains.
Some steps appear in every run, whether or not you configured them. Each job starts with a step that reclones your repository and a step that connects to your data platform. If either fails, the job fails, even though none of your commands has run yet. Every invocation also runs dbt deps automatically, so adding dbt deps to the Commands list is redundant.
After the built-in steps come the commands you configure. A new deploy job starts with dbt build in its Commands list, and Add command appends more. You can add or remove as many commands as you like, but at least one dbt command must remain. Commands labelled "dbt CLI" or "dbt v1" in the command reference are meant for those contexts. Which commands to run, and in what sequence, is covered in [ordering run commands](lesson:4.4).
Checkpoint 1 of 8· Check yourself
A job's Commands list contains only dbt build. A teammate wants to add dbt deps as the first command so that packages are installed before the build. What is the right response?
dbt deps is part of every job invocation without being listed, so adding it again only duplicates a built-in step.
“Every job invocation automatically includes the dbt deps command, meaning you don't need to add it to the Commands list in your job settings.”Source: docs.getdbt.com
2.How one failed step decides the job status
Run steps are chained: each step starts only if the one before it succeeded. When a step fails, nothing after it runs. The job then returns a non-zero exit code and finishes with the status Error. A run's final status is Success, Cancel or Error, and the outcome of each individual step feeds into it.
Here is a concrete case. A job's first four steps succeed, and the fifth, dbt run --select state:modified+ --full-refresh --fail-fast, fails. Every step queued after the fifth is never executed, and the whole job fails. Suppose a later step was a dbt test meant to validate the run. That test never ran at all, so the run history shows it as not executed rather than failed.
Checkpoint 2 of 8· Fill the gap
This is the fifth run step from the chaining example. Which flag makes the first model failure stop every model still in progress?
dbt run --select state:modified+ --full-refresh ? --fail-fast makes the first failure stop the entire connection for any models in progress, instead of letting the rest of the selection continue.
Source: docs.getdbt.comCheckpoint 3 of 8· Exam question
A deploy job's execution steps are configured as `dbt run --select finance`, then `dbt test --select finance`, then `dbt run --select marketing`. During a scheduled run, the `dbt test --select finance` step fails with test errors. What happens to the remaining step and the job's final status?
Correct answer: A — The `dbt run --select marketing` step is skipped entirely, and the job stops with an overall Error status shown in run history.
- A. Run steps in a dbt Cloud job are chained sequentially, so once a step in the list fails, every remaining listed command is skipped and the job as a whole is marked Error.
- B. Scoping a later command to a different set of models does not change the chaining behavior; a failed step still halts every command listed after it in the job.
- C. A failure in any listed command, including a test step, always drives the overall job status to Error — only checkbox commands like generate docs or source freshness can fail independently of that status.
- D. dbt Cloud jobs run unattended once triggered; there is no manual-approval gate that pauses a run between steps to ask whether a remaining command should execute.
Sources2
3.Commands list entries versus checkbox steps
A job can be given a step in two ways: by typing a dbt command into the Commands section, or by ticking a checkbox option. Both produce a run step, but they can lead to different outcomes. Source freshness shows the difference most clearly. To check that source data is current before models build, you can either add dbt source freshness to the Commands list or select the Run source freshness checkbox.
With the checkbox enabled, freshness runs before the deploy job's commands, and a failure there does not stop the job: if the later steps pass, the job can still succeed. Typing dbt source freshness into the Commands list makes it an ordinary chained step instead. A failure then stops everything queued after it. Use the checkbox when stale sources should be reported without blocking the build. Use the Commands list entry when building on stale data is worse than not building at all.
CI jobs offer a similar choice for Linting. When it is enabled, dbt lints the project's SQL files as the first step, and you decide what a lint error does: Stop running on error or Continue running on error. Documentation is a different case. On v2 jobs, every run refreshes Catalog metadata automatically, so no docs command is needed. Dedicated docs jobs are covered in [generating documentation](lesson:4.7).
Checkpoint 4 of 8· Check yourself
A team wants any failed freshness check to stop the job before dbt build runs. How should freshness be configured?
As a Commands list entry, freshness is a chained step, so its failure prevents the later dbt build step. A failure in the checkbox step lets the job succeed if later steps pass.
“When you add a dbt command in the Commands section, you can expect different outcomes compared to the checkbox option.”Source: docs.getdbt.com
4.What makes each command step fail
A step counts as failed only under that command's own rules, and the rules differ more than most people expect. dbt run fails when any model it builds errors. By default, the models downstream of the failed one are skipped. dbt test fails only on an error: a warning-severity test leaves the step passing unless warnings are treated as errors. dbt build runs models, tests, snapshots and seeds in DAG order. Any upstream failure skips everything downstream and exits with code 1.
| Step or setting | When the step fails | Effect inside the step |
|---|---|---|
| dbt run | Any built model errors | Downstream models of the failed model are skipped |
| dbt test | A test errors (warnings only if set as errors) | Failed tests on upstream resources skip downstream resources |
| dbt build | Any upstream resource fails | All downstream resources skipped; exit code 1 |
| Selector matching no nodes | Never: it is not considered a failure | The job still runs |
| --fail-fast | On the first failure | Stops the entire connection for models in progress |
| on_error: continue (dbt v1.12+) | The model still fails | Its downstream models still attempt to run |
Selectors cause the most surprises. If a selector matches several nodes and one of them fails, the step exits with code 1 and the commands after it do not run. If a selector matches nothing, for example dbt test --select one_specific_model after that model was renamed, the step is not a failure and the job still runs. A green run therefore does not prove that a selector selected anything. The skipping rule also has an opt-out: from dbt v1.12, setting on_error: continue on a model lets its downstream models attempt to run even though it failed.
Checkpoint 5 of 8· Match them up
Match each situation to how it affects the run step
Tap a term, then the definition that fits it.
Each command has its own failure rule. Only errors fail dbt test, an empty selection is never a failure, and dbt build skips everything downstream of a failure.
“If a selector doesn't match any nodes, it's not considered a failure.”Source: docs.getdbt.com
Checkpoint 6 of 8· Exam question
A production job has 'Run source freshness' and 'Generate docs on run' both enabled, with `dbt build` as the only listed command. During a run, `dbt build` fails partway through, after the source freshness check had already completed successfully. How does the 'Generate docs on run' step behave, and what is the final job status?
Correct answer: A — Docs generation still runs after the failed build step, but the job overall stays marked Error because the build command failed.
- A. The docs-generation checkbox step runs after the listed commands regardless of whether they succeeded, and its own outcome does not change the Error status already set by the failed build command.
- B. Checkbox commands are not part of the chained command list, so a failed listed command does not prevent docs generation from attempting to run afterward.
- C. A checkbox step succeeding cannot flip an already-failed job back to Success; the failed build command is what determines the overall Error status.
- D. Source freshness and docs generation are unrelated checks — completing a freshness check has no effect on whether the separate docs-generation step runs.
Sources2
5.Inspecting failed steps and rerunning from failure
Because a run is a list of steps, it is also debugged step by step. Open a run from Deploy > Run history to reach the job run details page. It shows the trigger, the commit SHA, the time spent in the scheduler queue, and every run step with its own logs. While a step is still running, only the tail of its log is shown: up to the last 1,000 lines or 0.5 MB, whichever comes first. A resource that is still running may not appear until its output reaches that tail. The full log is available once the step completes, and each step's logs can be downloaded individually.
On dbt v2 jobs, selecting a finished step opens a structured view that sorts each resource into Success, Reused, Failed, Warning, Running, Skipped or No-op. Command steps can also be downloaded as OpenTelemetry logs in Parquet format. The option appears only if the step produced one, and some steps, such as dbt deps, do not.
A run that ended in Error does not have to start again from the beginning. Rerun from failure invokes only the failed step and the steps skipped after it, which suits a long job whose last step broke. It requires dbt 1.6 or newer, a project dbt can still parse into a manifest, and a failed command that supports the retry command. Rerun from start reruns every step and is the safer choice when the fix changes something earlier in the chain.
Checkpoint 7 of 8· Put it in order
Put the steps for rerunning a job from its point of failure in order
- 1.Select Deploy, then Run History, and choose the errored job run
- 2.Fix the error, then save and commit the change to the Git repo
- 3.In the Run Summary tab, expand the run step marked as failed
- 4.On the job's Run page, click Rerun and choose Rerun from failure
- 5.Confirm the failed and skipped steps listed in the Rerun failed steps modal
You find the failed step, fix and commit the code, and only then rerun. The modal confirms which steps will run: the failed step plus any steps skipped after it.
“The modal lists the run steps that will be invoked: the failed step and any skipped steps.”Source: docs.getdbt.com
Checkpoint 8 of 8· Exam question
An admin is configuring a deploy job and needs to: increase model execution concurrency for faster runs, set a custom target name so project logic behaves differently for this job without adding environment variables, and pin this one job to an older dbt version while the environment keeps its current default. Which Advanced settings should the admin use? (Select all that apply)(Select 3)
Correct answers: A, B, C — Threads; Target name; dbt version override
- A. Increasing the threads setting raises how many models the job can build concurrently, directly addressing the request for faster execution.
- B. Setting a custom target name lets project logic branch on the target without introducing any new environment variables, matching the stated constraint.
- C. The dbt version override pins a single job to a specific dbt version independently of the environment's default version.
- D. Environment variable overrides were explicitly ruled out by the scenario, and none of the three stated needs require adding or changing variables.
Exam traps
Each one states something that sounds right. Open it to see what is actually true.
1.A job can only fail on one of the dbt commands you configured.Why is that wrong?
Every job also runs built-in steps that reclone the repository and connect to the data platform, and a failure in those steps affects the job status.
Covered in What a job run is made of
2.A failed Run source freshness checkbox step always fails the job, like any other chained step.Why is that wrong?
When freshness is enabled through the checkbox, the job can still succeed if the steps after it pass. Only freshness added as a command takes part in the normal chain.
Covered in Commands list entries versus checkbox steps
3.A selector that matches no models makes the step fail and stops the job.Why is that wrong?
An empty selection is not a failure. The job still runs, so a successful run can hide a selector that selected nothing.
Covered in What makes each command step fail
4.Any test that does not pass, including a warning, fails the dbt test step.Why is that wrong?
A test can pass, fail or warn. Unless warnings are treated as errors, only an error fails the command.
Covered in What makes each command step fail
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/docs/deploy/job-schedulerOfficial docs
“A collection of run steps, settings, and a trigger to invoke dbt commands against a project in the user's cloud data platform.”
↩︎ What a job run is made of - 2.https://docs.getdbt.com/docs/deploy/job-commandsOfficial docs
“every job will include a run step to reclone your repository and connect to your data platform”
↩︎ What a job run is made of“However, you need to have at least one dbt command.”
↩︎ What a job run is made of“If one of the run steps in the chain fails, then the subsequent steps aren't executed, and the job will fail.”
↩︎ How one failed step decides the job status“The failed job returns a non-zero exit code and "Error" job status”
↩︎ How one failed step decides the job status“Each run step can succeed or fail, which may determine the job's run status (Success, Cancel, or Error).”
↩︎ How one failed step decides the job status“add dbt source freshness to the Commands list or select the Run source freshness checkbox”
↩︎ Commands list entries versus checkbox steps“You don't need to add a docs command. Every job run refreshes Catalog metadata automatically.”
↩︎ Commands list entries versus checkbox steps“If any upstream resource fails, all downstream resources are skipped, and the command exits with an error code of 1.”
↩︎ What makes each command step fail“By default, if a model fails, its downstream models are also skipped.”
↩︎ What makes each command step fail“If you specified the --fail-fast flag, then the first failure will stop the entire connection for any models that are in progress.”
↩︎ What makes each command step fail“In dbt v1.12+, you can set on_error: continue on a model to allow its downstream models to still attempt to run despite the failure.”
↩︎ What makes each command step fail“A job consists of commands that are "chained" together and executed as run steps.”
↩︎ Key concept“every job will include a run step to reclone your repository and connect to your data platform”
↩︎ Exam trap 1“The job will still run if a selector doesn't match any models.”
↩︎ Exam trap 3“Unless you set warnings as errors, only an error fails the command.”
↩︎ Exam trap 4“Every job invocation automatically includes the dbt deps command, meaning you don't need to add it to the Commands list in your job settings.”
↩︎ Checkpoint“When you add a dbt command in the Commands section, you can expect different outcomes compared to the checkbox option.”
↩︎ Checkpoint“If a selector doesn't match any nodes, it's not considered a failure.”
↩︎ Checkpoint - 3.https://docs.getdbt.com/docs/deploy/deploy-jobsOfficial docs
“By default, it includes the dbt build command.”
↩︎ What a job run is made of“If the step fails, the job can succeed if subsequent steps pass.”
↩︎ Commands list entries versus checkbox steps“If the step fails, the job can succeed if subsequent steps pass.”
↩︎ Exam trap 2 - 4.https://docs.getdbt.com/docs/deploy/ci-jobsOfficial docs
“If this check runs into an error, dbt can either Stop running on error or Continue running on error.”
↩︎ Commands list entries versus checkbox steps - 5.https://docs.getdbt.com/docs/deploy/run-visibilityOfficial docs
“The job run details page displays job trigger, commit SHA, time spent in the scheduler queue, all the run steps and their logs”
↩︎ Inspecting failed steps and rerunning from failure“up to the last 1,000 lines or 0.5 MB, whichever comes first”
↩︎ Inspecting failed steps and rerunning from failure“Some steps, such as dbt deps, don't produce one.”
↩︎ Inspecting failed steps and rerunning from failure - 6.https://docs.getdbt.com/docs/deploy/retry-jobsOfficial docs
“The job command that failed in the run must be one that supports the retry command.”
↩︎ Inspecting failed steps and rerunning from failure“In the upper right corner, click Rerun and choose Rerun from start or Rerun from failure.”
↩︎ Inspecting failed steps and rerunning from failure“The modal lists the run steps that will be invoked: the failed step and any skipped steps.”
↩︎ Checkpoint