dbt-common
raw JSON → 1.37.3 verified Tue May 12 auth: no python install: stale quickstart: stale
dbt-common is a Python library that provides shared common utilities used by dbt-core and various dbt adapter implementations. It centralizes functionalities to ensure consistency and efficiency across the dbt ecosystem. The library is actively maintained by dbt Labs, with a current version of 1.37.3, and typically follows the release cadence of `dbt-core` and related adapter packages.
pip install dbt-common Common errors
error google.protobuf.runtime_version.VersionError: Detected incompatible Protobuf Gencode/Runtime versions when loading types.proto ↓
cause This error occurs when the version of the `protobuf` runtime installed in your environment is older than the version used to generate the protobuf code within `dbt-common` or a related dbt package, leading to a version mismatch.
fix
Upgrade your
protobuf installation to meet or exceed the version required by dbt-common. A common fix is pip install --upgrade protobuf or ensuring your protobuf version aligns with the minimum required by dbt-common (e.g., >=5.28.3,<=6.0 as seen in older issues). error ModuleNotFoundError: No module named 'google' ↓
cause This error typically arises when `dbt-core` or one of its adapters (which depend on `dbt-common`) attempts to import `google.protobuf` or other `google` modules, but the `protobuf` package (or `google-api-core`) is not installed or incorrectly installed in the environment.
fix
Install the
protobuf package using pip: pip install protobuf. If the issue persists, ensure google-api-core is also installed (pip install google-api-core). error ImportError: cannot import name 'RecordReplayIssue' from 'dbt_common.events.types' ↓
cause This `ImportError` indicates an incompatibility between the installed version of `dbt-common` and other dbt packages like `dbt-adapters` or `dbt-core`, where a specific event type (`RecordReplayIssue`) is expected but missing or located differently in the `dbt-common.events.types` module.
fix
Ensure all dbt-related packages (
dbt-core, dbt-common, and any dbt- adapters like dbt-snowflake) are updated to compatible versions. A common solution is to upgrade all of them together: pip install --upgrade dbt-core dbt-common dbt-adapters dbt-<your-adapter>. error mashumaro.exceptions.UnserializableField: Field “schema” of type Optional[str] in JSONObjectSchema is not serializable. ↓
cause This serialization error, often seen in dbt's interaction with `dbt-common`, suggests a mismatch or misconfiguration in how data classes (potentially handled by `mashumaro` which `dbt-common` might use) are attempting to serialize or deserialize fields, particularly when `Optional` types are involved.
fix
This often points to version incompatibilities between
dbt-core, dbt-common, and underlying serialization libraries. Ensure all dbt packages are updated to their latest compatible versions (pip install --upgrade dbt-core dbt-common dbt-adapters dbt-<your-adapter>). If using custom code, review data class definitions and ensure they align with expected serialization patterns. Warnings
breaking Major versions of `dbt-core` (e.g., v1 to v2) may include breaking changes that impact `dbt-common` and its consumers, particularly adapter plugins and custom implementations that rely on dbt's internal Python interfaces. These changes are typically communicated in dbt's release notes for adapter maintainers. ↓
fix Refer to the `dbt-core` release notes and migration guides for adapter developers. Update your adapter implementations to align with the new Python interfaces exposed or used by `dbt-common`.
breaking Changes to dbt's metadata interfaces, including artifacts (like `manifest.json`, `catalog.json`) and structured logging, are considered breaking for `dbt-common`'s consumers if fields are deleted, renamed, or their types/defaults change without backward compatibility. ↓
fix Ensure your tools or integrations parsing dbt artifacts are updated to handle the new schema versions. Monitor dbt Developer Hub for detailed artifact schema changes.
deprecated The `DBT_` environment variable prefix has been deprecated for custom variables to prevent collisions with dbt's internal variables. New dbt environment variables are now prefixed with `DBT_ENGINE`. ↓
fix Update any custom environment variables currently using the `DBT_` prefix to a different, non-colliding prefix, or ensure they do not conflict with dbt's internal `DBT_ENGINE` variables.
gotcha `dbt-common` is a foundational library, not typically intended for direct end-user application development. Its utilities are primarily consumed by `dbt-core` and dbt adapter implementations. Expect minimal direct documentation for independent usage. ↓
fix When using dbt, interact primarily with `dbt-core` or specific adapters. If you are developing a dbt adapter or extending `dbt-core`, refer to the `dbt-common` source code and dbt Labs' developer guides for internal API usage.
Install compatibility stale last tested: 2026-05-12
python os / libc status wheel install import disk
3.10 alpine (musl) wheel - - 70.2M
3.10 alpine (musl) - - - -
3.10 slim (glibc) wheel 5.6s - 71M
3.10 slim (glibc) - - - -
3.11 alpine (musl) wheel - - 74.6M
3.11 alpine (musl) - - - -
3.11 slim (glibc) wheel 5.4s - 75M
3.11 slim (glibc) - - - -
3.12 alpine (musl) wheel - - 66.0M
3.12 alpine (musl) - - - -
3.12 slim (glibc) wheel 4.8s - 67M
3.12 slim (glibc) - - - -
3.13 alpine (musl) wheel - - 65.7M
3.13 alpine (musl) - - - -
3.13 slim (glibc) wheel 4.7s - 67M
3.13 slim (glibc) - - - -
3.9 alpine (musl) wheel - - 69.3M
3.9 alpine (musl) - - - -
3.9 slim (glibc) wheel 6.5s - 70M
3.9 slim (glibc) - - - -
Imports
- __version__
import dbt_common; print(dbt_common.__version__) - DbtCommonError
from dbt_common.exceptions import DbtCommonError
Quickstart stale last tested: 2026-04-24
import dbt_common
from dbt_common.exceptions import DbtCommonError
print(f"dbt-common version: {dbt_common.__version__}")
try:
raise DbtCommonError("This is a dbt common error.")
except DbtCommonError as e:
print(f"Caught expected error: {e}")