Skip to content

dct doctor

Diagnose why dct can't reach your data.

dct doctor [OPTIONS]

Reports how dbt Charts was installed, whether your project and profiles.yml were found, and whether each configured source has its warehouse adapter installed. Paste the output into a support ticket or hand it to an AI assistant. The default run is offline and opens no warehouse connection.

$ dct doctor

 ✓ install     dbt Charts 1.8.0 (uv tool), Python 3.13.1 at /home/ana/.local/share/uv/tools/dbt-charts/bin/python
 ✓ project     dbt_charts.yml at /home/ana/shop; dbt project at /home/ana/shop
 ✓ profiles    /home/ana/.dbt/profiles.yml
 ✗ adapter     warehouse: the dbt-snowflake adapter is not installed in this Python environment
               uv tool install "dbt-charts[snowflake]"
 ✓ adapter     local: duckdb adapter installed
 – connection  connections not tested
               run `dct doctor --with-warehouse`

1 failed, 0 warnings.

Marks: ✓ pass, ! warn, ✗ fail, – skip.

Options

Option Description
--with-warehouse Also connect to each warehouse source with SELECT 1
--json Machine-readable report (see JSON output)
--project-dir PATH Where to start looking for the project (default: the current directory)

What it checks

Checks run in this order. One failing check never stops the next.

install

The dbt Charts version, the install method (uv tool, pip, or editable), and the Python interpreter running dct. Always pass. An adapter installed into a different Python than the one shown here is the most common cause of a "not installed" error.

project

Looks for dbt_charts.yml or dbt_project.yml in the starting directory and its parents. warn when neither is found; the adapter and connection checks are then skipped.

profiles

Locates profiles.yml using the same search order as the rest of dct: DBT_PROFILES_DIR, the project directory, then ~/.dbt/. skip when there is no dbt project, fail when no profiles.yml is found. A dbt_profile source that sets profiles_dir gets its own check (with source set) against that directory; the default search is reported unless every dbt_profile source sets its own.

adapter

One check per source in dbt_charts.yml. It imports the warehouse adapter the source needs; a missing one fails with the extra to install. A dbt_profile source is checked against the adapter its profile target names, so a missing profiles.yml or an unknown profile fails here too. File sources (csv, json, parquet), http sources, and databases dbt Charts runs natively (such as sqlite) need no dbt adapter and are skip. If the sources: block itself cannot be loaded, a single adapter check without a source reports why.

connection

Without --with-warehouse, a single skip. With it, one check per source: SELECT 1 against the warehouse, failing with the connection error. Sources whose adapter check did not pass, and file sources, are skip.

JSON output

dct doctor --json prints a DoctorReport:

Field Description
success false when any check is fail
checks Every check, in the order above
checks[].code install, project, profiles, adapter, or connection
checks[].source Source name; set on per-source adapter, connection, and profiles checks
checks[].status pass, warn, fail, or skip
checks[].message What was found
checks[].hint The command or flag that fixes it, when there is one

Fields that are unset are omitted. This shape is version 1: the code values and field names are stable, and a rename ships behind a version bump.

Exit code

1 when any check is fail, otherwise 0. A warn or skip never fails the run.

Examples

dct doctor                                   # Offline checks
dct doctor --with-warehouse                  # Also test each connection
dct doctor --json | jq '.checks[] | select(.status == "fail")'