{"id":627,"library":"dbt-common","title":"dbt-common","description":"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.","status":"active","version":"1.37.3","language":"python","source_language":"en","source_url":"https://github.com/dbt-labs/dbt-common.git","tags":["dbt","utility","common","library","etl","data-transformation"],"install":[{"cmd":"pip install dbt-common","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Used for file path matching and handling.","package":"pathspec"},{"reason":"Likely for object serialization/deserialization.","package":"mashumaro"},{"reason":"For cross-platform colored terminal output.","package":"colorama"},{"reason":"For ISO 8601 date/time parsing and formatting.","package":"isodate"},{"reason":"For Protocol Buffers definitions used in dbt communication and artifacts.","package":"dbt-protos"},{"reason":"For deep comparison of data structures.","package":"deepdiff"},{"reason":"Core templating engine used throughout dbt, including for SQL generation.","package":"jinja2"},{"reason":"For robust date/time parsing and manipulation.","package":"python-dateutil"},{"reason":"A lightweight table-oriented data analysis library, potentially for internal data handling.","package":"agate"},{"reason":"For backporting features from newer `typing` modules to older Python versions.","package":"typing-extensions"},{"reason":"For validating JSON data against schemas, crucial for dbt artifacts.","package":"jsonschema"},{"reason":"Google's Protocol Buffers for data serialization.","package":"protobuf"},{"reason":"For making HTTP requests, common in various utility functions.","package":"requests"}],"imports":[{"symbol":"__version__","correct":"import dbt_common; print(dbt_common.__version__)"},{"symbol":"DbtCommonError","correct":"from dbt_common.exceptions import DbtCommonError"}],"quickstart":{"code":"import dbt_common\nfrom dbt_common.exceptions import DbtCommonError\n\nprint(f\"dbt-common version: {dbt_common.__version__}\")\n\ntry:\n    raise DbtCommonError(\"This is a dbt common error.\")\nexcept DbtCommonError as e:\n    print(f\"Caught expected error: {e}\")","lang":"python","description":"This quickstart demonstrates how to import the `dbt_common` library and access its version. It also shows how to import and catch a base exception class, `DbtCommonError`, which is part of its utilities, illustrating basic programmatic interaction. Note that `dbt-common` is primarily an internal utility for `dbt-core` and adapters, so direct end-user application development with it is rare."},"warnings":[{"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`.","message":"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.","severity":"breaking","affected_versions":"All major version upgrades of `dbt-core` (e.g., 1.x.x to 2.x.x)"},{"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.","message":"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.","severity":"breaking","affected_versions":"Any minor or major version where metadata interface versions are bumped (e.g., dbt Core v1.x.x to v1.y.x or v2.x.x)."},{"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.","message":"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`.","severity":"deprecated","affected_versions":"dbt Core v1.10 onwards, impacting users with custom `DBT_` prefixed environment variables."},{"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.","message":"`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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-05-12T16:56:02.859Z","next_check":"2026-06-26T00:00:00.000Z","problems":[{"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).","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.","error":"google.protobuf.runtime_version.VersionError: Detected incompatible Protobuf Gencode/Runtime versions when loading types.proto"},{"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`).","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.","error":"ModuleNotFoundError: No module named 'google'"},{"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>`.","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.","error":"ImportError: cannot import name 'RecordReplayIssue' from 'dbt_common.events.types'"},{"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.","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.","error":"mashumaro.exceptions.UnserializableField: Field “schema” of type Optional[str] in JSONObjectSchema is not serializable."}],"ecosystem":"pypi","meta_description":null,"install_score":0,"install_tag":"stale","quickstart_score":0,"quickstart_tag":"stale","pypi_latest":"1.38.0","install_checks":{"last_tested":"2026-05-12","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"70.2M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":5.6,"import_time_s":null,"mem_mb":null,"disk_size":"71M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"74.6M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":5.4,"import_time_s":null,"mem_mb":null,"disk_size":"75M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"66.0M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":4.8,"import_time_s":null,"mem_mb":null,"disk_size":"67M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"65.7M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":4.7,"import_time_s":null,"mem_mb":null,"disk_size":"67M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"69.3M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":6.5,"import_time_s":null,"mem_mb":null,"disk_size":"70M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null}]},"quickstart_checks":{"last_tested":"2026-04-24","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}