What causes NOTEBOOK_EXECUTION_ERROR?

A Python, Scala, or SQL cell raised an unhandled exception — such as a KeyError, NullPointerException, or SQL error — that propagated to the notebook execution layer. A %run magic command called a sub-notebook that itself failed, propagating the failure to the parent notebook. A widget parameter passed to the notebook at runtime had an unexpected value that caused a cell to fail during parameter validation

How do I fix NOTEBOOK_EXECUTION_ERROR?

Step 1: Open the failed notebook run output in the Databricks Jobs UI to identify the exact cell and exception message.. Step 2: Reproduce the error interactively by running the notebook with the same parameters, or inspect the cell's output in the run history.. Step 3: Add try/except error handling around cells that interact with external data sources, and use dbutils.notebook.exit() to return a structured error message.. Step 4: For %run sub-notebook failures, check the sub-notebook's run output separately — the parent notebook error will reference the sub-notebook path.

High severityexecution

Power BI Refresh Error:
NOTEBOOK_EXECUTION_ERROR

What does this error mean?

A Databricks notebook job failed because a cell raised an unhandled exception, causing the notebook run to terminate with a NOTEBOOK_EXECUTION_ERROR and recording the failing cell's output.

Common causes

1A Python, Scala, or SQL cell raised an unhandled exception — such as a KeyError, NullPointerException, or SQL error — that propagated to the notebook execution layer
2A %run magic command called a sub-notebook that itself failed, propagating the failure to the parent notebook
3A widget parameter passed to the notebook at runtime had an unexpected value that caused a cell to fail during parameter validation

How to fix it

1Step 1: Open the failed notebook run output in the Databricks Jobs UI to identify the exact cell and exception message.
2Step 2: Reproduce the error interactively by running the notebook with the same parameters, or inspect the cell's output in the run history.
3Step 3: Add try/except error handling around cells that interact with external data sources, and use dbutils.notebook.exit() to return a structured error message.
4Step 4: For %run sub-notebook failures, check the sub-notebook's run output separately — the parent notebook error will reference the sub-notebook path.

Frequently asked questions

Can I catch NOTEBOOK_EXECUTION_ERROR in a parent workflow?

Yes. Databricks Workflows can be configured with conditional tasks that run on failure, allowing you to trigger notification or cleanup logic when a notebook task fails.

How do I get the actual exception from the notebook run API?

Call GET /api/2.1/jobs/runs/get-output with the run_id. The response includes the notebook_output field containing the last cell's output and the error field with the exception message.