What causes BUNDLE_DEPLOYMENT_FAILED?

The bundle references a cluster policy, instance pool, or secret scope that does not exist in the target workspace. The deploying service principal lacks the required permissions to create or modify jobs, pipelines, or clusters. A resource definition in the YAML references an invalid or unsupported field for the target Databricks runtime version. A previous partial deployment left the workspace in a conflicting state

How do I fix BUNDLE_DEPLOYMENT_FAILED?

Step 1: Run 'databricks bundle validate' locally to catch schema and reference errors before deploying.. Step 2: Review the deployment error output — the CLI prints the specific resource that failed and the API error message.. Step 3: Verify that all referenced resources (cluster policies, instance pools, secret scopes) exist in the target environment.. Step 4: Confirm the service principal used in the CI/CD pipeline has at least CAN_MANAGE permissions on jobs and pipelines.. Step 5: If a previous partial deployment is blocking, run 'databricks bundle destroy' to clean up and then redeploy.

High severityconfiguration

Power BI Refresh Error:
BUNDLE_DEPLOYMENT_FAILED

What does this error mean?

A Databricks Asset Bundle (DAB) deployment via the CLI command failed, meaning one or more workspace resources defined in the bundle could not be created or updated.

Common causes

1The bundle references a cluster policy, instance pool, or secret scope that does not exist in the target workspace
2The deploying service principal lacks the required permissions to create or modify jobs, pipelines, or clusters
3A resource definition in the YAML references an invalid or unsupported field for the target Databricks runtime version
4A previous partial deployment left the workspace in a conflicting state

How to fix it

1Step 1: Run 'databricks bundle validate' locally to catch schema and reference errors before deploying.
2Step 2: Review the deployment error output — the CLI prints the specific resource that failed and the API error message.
3Step 3: Verify that all referenced resources (cluster policies, instance pools, secret scopes) exist in the target environment.
4Step 4: Confirm the service principal used in the CI/CD pipeline has at least CAN_MANAGE permissions on jobs and pipelines.
5Step 5: If a previous partial deployment is blocking, run 'databricks bundle destroy' to clean up and then redeploy.

Frequently asked questions

Can I deploy a bundle to multiple environments from one configuration file?

Yes. DABs support target environments (dev, staging, prod) defined in databricks.yml. Each target can override workspace URLs, cluster sizes, and variable values, letting you promote the same bundle definition across environments.

What permissions does the deploying service principal need?

At minimum: CAN_MANAGE on all jobs and DLT pipelines, CAN_USE on cluster policies, and CAN_READ on secret scopes referenced by the bundle. For first-time deployments that create new resources, workspace admin or the IS_OWNER permission on the target folder is also required.