dbt-labs/dbt-core · error · RuntimeError

An unexpected error occurred during package installation: {e

Error message

An unexpected error occurred during package installation: {e}

What it means

This RuntimeError wraps any failure from the embedded Python snippet that pip-installs user-requested packages (e.g. packages named in `dbt deps` / package config) during BigQuery adapter setup. It fires when `subprocess.run([sys.executable, '-m', 'pip', 'install', ...])` raises — most commonly CalledProcessError from a non-zero pip exit code, but also pip-not-found or environment errors. The original pip exception `e` is interpolated into the message so the root cause is visible.

Source

Thrown at crates/dbt-adapter/src/python/bigquery/mod.rs:653

    try:
        result = subprocess.run(
            pip_command,
            capture_output=True,
            text=True,
            check=True,
            encoding="utf-8",
        )
        if result.stdout:
            print(f"pip output:\n{result.stdout.strip()}")
        if result.stderr:
            print(f"pip warnings/errors:\n{result.stderr.strip()}")
        print(
            f"Successfully installed the following packages: {', '.join(packages_to_install)}"
        )

    except Exception as e:
        raise RuntimeError(
            f"An unexpected error occurred during package installation: {e}"
        )
"#
}

View on GitHub (pinned to 0267ce9170)

Solutions

Read the wrapped `{e}` message and re-run the failing `pip install` command manually to see full pip output
Fix the package spec (name typo, version pin, or Python-version compatibility) in the package config
Check network/proxy access and any configured index (pip config, PIP_INDEX_URL)
Verify `python -m pip` works in the environment; repair or upgrade pip if broken
If the package is already installed with an incompatible version, uninstall or upgrade it manually

Example fix

// before (user package config)
packages: ["google-cloud-bigquery==99.0.0"]
// after
packages: ["google-cloud-bigquery>=3.0,<4.0"]  // version that exists and supports your Python

Defensive patterns

Strategy: try-catch

Validate before calling

import importlib.metadata, packaging.requirements
req = packaging.requirements.Requirement("google-cloud-bigquery>=3.0")
try:
    importlib.metadata.version(req.name)
    installed = True
except importlib.metadata.PackageNotFoundError:
    installed = False
# also verify pip works first: subprocess.run([sys.executable, '-m', 'pip', '--version'], check=True)

Type guard

def is_pip_ok() -> bool:
    import subprocess, sys
    return subprocess.run([sys.executable, "-m", "pip", "--version"], capture_output=True).returncode == 0

Try / catch

try:
    install_packages(packages)
except RuntimeError as e:
    logger.error("package install failed: %s", e)  # inspect wrapped pip error
    raise SystemExit(1)

Prevention

Pin package versions that exist and support your Python version
Verify network/index access before running installs in CI
Check installed packages/satisfying versions before install (the code already skips satisfied requirements)
Keep pip upgraded in the target environment

When it happens

Trigger: The Python helper function source generated by get_install_packages_function_source is executed and `pip install <packages>` exits non-zero (CalledProcessError), pip is missing/broken, or any other exception occurs inside the install block — reached via convert_py_to_ipynb.

Common situations: A required package name/version spec doesn't exist on PyPI or is incompatible with the Python version; no network access or a private index is needed; pip itself is broken or points at a different interpreter; disk space exhaustion during install.

Related errors

AI-assisted analysis of dbt-labs/dbt-core@0267ce9170 (2026-09-07). Data as JSON: /api/errors/1479067b7a351571. Report an issue: GitHub.