Version compatibility Preview
The dbt Fusion engine, its language server (LSP), and the dbt VS Code extension work together to power local development. This page explains how their versions relate, which combinations are compatible, and how to verify you have matching binaries.
How versioning works
Fusion ships as a single binary that provides both the command-line interface (CLI) and the language server (LSP). Because the CLI and LSP come from the same binary, they always share the same version and can't be mismatched.
The dbt VS Code extension keeps its own release version because it follows the VS Code Marketplace release lifecycle. To make compatibility explicit, each extension release declares the range of dbt Fusion engine versions it supports. When the extension starts the LSP, it checks the installed Fusion version against that range and surfaces an actionable error if they don't match.
| Loading table... |
Compatibility matrix
The following table maps each dbt VS Code extension version to the dbt Fusion engine versions it supports. If you let the extension download and manage Fusion for you, it always installs a compatible version automatically — you only need this table if you install or pin binaries manually.
| Loading table... |
A dash (-) in the Max column means there is no upper bound yet. Any Fusion release at or above the minimum is supported.
Check your installed versions
To confirm your setup is within the supported range, check the version of the dbt Fusion engine you have installed:
dbt --version
For a machine-readable summary you can paste into a bug report or parse in tooling, add the --format json flag:
dbt --version --format json
For details on the full output, refer to About dbt --version.
Verify binaries for manual and air-gapped installs
If you install Fusion manually in an air-gapped or firewall-restricted environment where the extension can't download binaries for you, use the compatibility matrix to pick a version that matches your dbt VS Code extension, then verify the download before you distribute it.
-
From the compatibility matrix, note the Fusion version range for your extension version.
-
Download the matching Fusion binary and its checksum file.
-
Verify the checksum before installing or distributing the binary:
- Mac / Linux
- Windows (PowerShell)
shasum -a 256 -c checksums-0.36.txtGet-FileHash .\dbt.exe -Algorithm SHA256Compare the printed hash against the value in the checksum file.
-
Point the dbt VS Code extension at the verified binary using the
dbt.fusionPathsetting. Refer to dbt extension settings.
For network and proxy requirements, and how to pre-build an offline bundle, refer to Networking requirements.
Known-bad releases
If a shipped Fusion release is later found to contain a regression, dbt Labs flags it as a known-bad release. When you have a flagged version installed, the dbt VS Code extension shows a warning notification telling you which version to update to, even if that version is otherwise within the supported range.
Air-gapped users who don't have outbound network access can distribute the known-bad releases manifest alongside their binary bundle and point the extension at the local copy with the dbt.badReleasesManifestPath setting. Refer to dbt extension settings.
Troubleshooting version issues
If the extension can't find, start, or verify a compatible Fusion binary, it surfaces an actionable error with a link or button to resolve it. Refer to the dbt VS Code extension troubleshooting section for the full list of messages and fixes.
Was this page helpful?
This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.
