My Databricks job keeps failing, how do I fix it?

Summary

• Start with the failed run: click Jobs & Pipelines in the sidebar, open the job, and find the failed task in the Runs tab's matrix view. Its Task run details page shows the output and error message.
• The Databricks troubleshooting guide gives a data quality issue, a misconfiguration and insufficient compute resources as example causes. Upstream outages and concurrency limits also stop runs.
• After the fix, Repair run re-runs only the unsuccessful tasks and their dependents with the current settings. It works on jobs with two or more tasks; re-trigger a single-task job with Run now.
• To stop repeats, add a retry policy, duration thresholds and failure notifications, and run the job as a service principal so it doesn't break when its owner leaves.

My Databricks job keeps failing, how do I fix it?

Find the failing task, read its error, fix the cause, then repair the run. In the Lakeflow Jobs UI, the Runs tab's matrix view shows every task's history across runs, so a task that fails each time stands out. Causes to check include bad input data, a misconfigured task, too little compute, a missing library and missing privileges. Once the cause is fixed, Repair run re-runs only what didn't succeed.

How do you find out why a job run failed?

1. Click Jobs & Pipelines in the sidebar, then click the job name. The Runs tab lists active and completed runs, including failed ones.
2. Use the matrix view to spot the failed task. A task can be unsuccessful because it failed, or because it was skipped after a task it depends on failed.
3. Click the task to open the Task run details page, which shows its output, error message and metadata.
4. For a slow task on classic compute, open the Spark UI and start with the event timeline. For serverless jobs, use query history and the query profile.
5. For help reading the error, open the failed job and select Diagnose Error to use Genie Code.

What usually causes repeated job failures?

Cause	What you'll see	How to fix it
Task misconfiguration	An error that points at the task's settings	Click Edit task, update the configuration, then click Save task
Insufficient compute	Failures tied to the cluster, such as insufficient instances	Change the number of workers or instance types, Swap to another cluster, or ask an admin to raise quotas in the cloud account and region
Concurrency limit	Runs skipped because the job already has its maximum number of active runs	Wait for active runs, raise Maximum concurrent runs, or enable queueing
Upstream or data problem	Failures after bad input or an unavailable external source	Fix the source or the data, then repair the run
Missing Python library	ModuleNotFoundError, raised when an import can't find a module	Add the library to the task's libraries, or to the job environment on serverless compute
Privileges	Failures reading or writing data, including after privileges change mid-run	Grant the Run as identity what it needs; Databricks recommends a service principal
Schema mismatch on a Delta write	A write fails because a column doesn't exist in the target table or a type can't be safely cast	If the change is intended, use WITH SCHEMA EVOLUTION or the mergeSchema option

How do you repair a failed run?

Fix the cause first. Unsuccessful tasks re-run with the current job and task settings, so an edited notebook path or cluster setting takes effect. Then click the failed run in the Start time column or the matrix view and click Repair run. The dialog lists the unsuccessful tasks and their dependents, and parameters you enter there override existing values. Successful tasks don't re-run.
Two cautions from the docs. Repair needs a job with two or more tasks; re-trigger a single-task job with Run now. And each repaired task starts from the beginning, so a task that wrote part of its output before failing can duplicate data. Prefer overwrite or merge over append.

How do you stop the job from failing again?

Setting	What it does
Retries	A retry policy sets how many times, and how often, failed task runs retry. For most configurations the default is no retries; serverless jobs auto-optimize retries by default.
Duration thresholds	A Warning value marks the expected run time and a Timeout value sets the maximum. With retries configured, the timeout applies to each retry.
Notifications	Alerts on start, success, failure or a duration warning, sent to email or to admin-configured destinations such as Slack, PagerDuty or a webhook.
Run as a service principal	Separates job privileges from the owner's, so jobs don't break when the owner leaves
Declarative Automation Bundles	Bring source control, code review, testing and CI/CD to job definitions

In a bundle, these safeguards are documented keys:

resources:
  jobs:
    nightly_job:
      name: nightly_job
      email_notifications:
        on_failure:
          - someone@example.com
      tasks:
        - task_key: main_task
          notebook_task:
            notebook_path: ../src/notebook.ipynb
          # example values; tune them for your job
          max_retries: 2
          min_retry_interval_millis: 60000
          retry_on_timeout: true
          timeout_seconds: 3600

FAQs

How long does Databricks keep job run history?

Databricks keeps run history for up to 60 days for jobs and pipelines. To keep runs longer, export notebook results to HTML or configure log delivery on job compute; if you can access the system.lakeflow schema, you can also query records of job runs and tasks across your account.

Why does my job fail when scheduled but work in my notebook?

Check identity and compute. The job uses the privileges of its Run as user, which may differ from yours, and its compute needs every library your notebook relied on.

Can I get an alert every time a task fails?

Yes. Job-level notifications aren't sent when failed tasks are retried, so add task notifications to hear about each failed attempt. In a bundle, alert_on_last_attempt under notification_settings limits a task's alerts to the last retry.