What causes BUNDLE_VALIDATION_FAILED?

A required field is missing in a job, pipeline, or cluster definition within databricks.yml. A variable reference uses the wrong substitution syntax (e.g. ${var.name} vs ${bundle.name}). A resource references a path, library, or artifact that does not resolve within the bundle directory. An unsupported field was added that is valid in the REST API but not yet supported by the DAB schema

How do I fix BUNDLE_VALIDATION_FAILED?

Step 1: Run 'databricks bundle validate' locally to see the full list of validation errors with line numbers.. Step 2: Fix any missing required fields — the output names the schema path (e.g., resources.jobs.my_job.tasks[0].task_key).. Step 3: Check variable substitution syntax — bundle variables use ${var.my_var} and bundle-level values use ${bundle.environment}.. Step 4: Ensure all notebook and file paths referenced in the bundle are relative to the bundle root or use correct workspace paths.. Step 5: Consult the Databricks configuration reference for the supported fields for your CLI version.

Medium severityconfiguration

Power BI Refresh Error:
BUNDLE_VALIDATION_FAILED

What does this error mean?

The 'databricks bundle validate' command detected structural or semantic errors in the bundle YAML configuration before any deployment was attempted.

Common causes

1A required field is missing in a job, pipeline, or cluster definition within databricks.yml
2A variable reference uses the wrong substitution syntax (e.g. ${var.name} vs ${bundle.name})
3A resource references a path, library, or artifact that does not resolve within the bundle directory
4An unsupported field was added that is valid in the REST API but not yet supported by the DAB schema

How to fix it

1Step 1: Run 'databricks bundle validate' locally to see the full list of validation errors with line numbers.
2Step 2: Fix any missing required fields — the output names the schema path (e.g., resources.jobs.my_job.tasks[0].task_key).
3Step 3: Check variable substitution syntax — bundle variables use ${var.my_var} and bundle-level values use ${bundle.environment}.
4Step 4: Ensure all notebook and file paths referenced in the bundle are relative to the bundle root or use correct workspace paths.
5Step 5: Consult the Databricks configuration reference for the supported fields for your CLI version.

Frequently asked questions

Does 'databricks bundle validate' require a connection to the Databricks workspace?

It can run offline for schema-level validation, but it connects to the workspace to resolve remote references (e.g., cluster policy IDs) and verify that referenced resources exist. Use the --no-remote flag for purely local checks.

How do I keep the bundle schema up to date as the CLI evolves?

The CLI embeds the current schema. Update the Databricks CLI regularly with your package manager (e.g., brew upgrade databricks). The VS Code Databricks extension also provides real-time YAML schema validation as you edit the bundle.