/migrating-dbt-core-to-v2

name: migrating-dbt-core-to-v2
description: Use when a user needs help triaging dbt-core to dbt v2 migration errors. Runs dbt-autofix first, then classifies remaining errors into actionable categories (auto-fixable, guided fixes, needs input, blocked).
allowed-tools: "Bash(dbt:*), Bash(git:*), Bash(uvx:*), Read, Write, Edit, Glob, Grep, WebFetch(domain:api.github.com)"
compatibility: "dbt v2"
metadata:
  author: dbt-labs

dbt v2 Migration Triage Assistant

Help users understand which v2 migration errors they can fix themselves vs which are blocked on v2 updates. Your role is to **classify and triage** migration issues, NOT to fix everything automatically.

**Key principle**: Not all migration issues are fixable in your project. Some require v2 updates. Migration is iterative — success means making progress and knowing what's blocking you.

Mandatory execution order

This skill is a strict procedure, not general guidance.

The assistant must follow this order: 1. Step 0: Ask whether to run `dbt debug` 2. Step 1: Run or confirm `dbt-autofix`, then review its changes 3. Step 2: Classify remaining issues 4. Only after Steps 0–2 may the assistant propose or apply manual fixes

Hard rules:

• Do not inspect project files before Step 0 is completed or explicitly skipped
• Do not classify issues before Step 1 is complete
• Do not edit files before presenting the autofix review and classification summary
• If these rules are violated, acknowledge the violation, state which step was missed, and execute that step now before continuing
• **Focus on errors**: For `dbt1065` package version compatibility warnings specifically (e.g. `Package '<package_name>' requires dbt version [>=1.2.0, <2.0.0]`) — ignore these. If autofix was run, it will have already upgraded packages that need upgrading. If `dbt1065` warnings persist after autofix, no manual package updates are needed.

Additional Resources

• [References Overview](references/README.md) — index of all reference material
• [Error Patterns Reference](references/error-patterns-reference.md) — full catalog of error patterns by category
• [Classification Categories](references/classification-categories.md) — detailed category definitions with sub-patterns, signals, fixes, and risk notes

Repro Command Behavior

The base command defaults to `dbt compile`, or a different command if the user specifies one (e.g. `dbt build`, `dbt test --select tag:my_tag`), or the contents of `repro_command.txt` if that file exists in the project root.

**Normalize the static-analysis mode on whichever command you land on**: if it does not already contain a `--static-analysis` flag, append `--static-analysis strict`. If it already specifies one explicitly (e.g. `--static-analysis off` or `unsafe`), leave it as-is — do not append a second, conflicting flag. This applies whether the command came from the user or from `repro_command.txt`; a file containing bare `dbt compile` still gets `strict` appended.

Plain `dbt compile` still performs full parsing, graph building, and config compilation, and surfaces real failures from those checks. But without strict mode, static analysis findings about column/schema existence are only reported as warnings, not build-blocking failures. A project can report zero *errors* under plain `dbt compile` while strict mode fails it on real column-existence problems. Always run with strict mode at least once before telling the user the project is v2-compatible.

Step 0: Validate Credentials with dbt debug

**Before doing anything else**, ask the user if they'd like to verify their credentials work on v2.

Ask: "Would you like to start by running `dbt debug` to verify your credentials and connection work on v2? This catches environment issues early before we dig into migration errors."

If the user agrees:

Run:

dbt debug

**What to check in the output:**

• **Connection test**: Does it say "Connection test: OK"? If not, credentials need fixing first — this is NOT a migration issue
• **profiles.yml found**: Is it loading the correct profile/target?
• **Dependencies**: Are packages installed?

If `dbt debug` fails:

• **Connection/auth errors**: Help the user fix their `profiles.yml` and credentials before proceeding. Migration triage can't begin until the connection works.
• **Profile not found**: Help locate or configure the correct profile for v2
• **Other errors**: Note them and proceed — some `dbt debug` checks may not be relevant to the migration

If `dbt debug` succeeds:

Confirm the environment is healthy and proceed to Step 1.

If the user skips this step:

That's fine — proceed to Step 1. But if connection errors appear later during classification, circle back and suggest running `dbt debug`.

Step 1: Run dbt-autofix (REQUIRED FIRST STEP)

**Before classifying any errors**, ensure the user has run dbt-autofix on their project.

Check if autofix has been run:

1. Ask user: "Have you run dbt-autofix on this project yet?" 2. Check git history for recent autofix-related commits 3. Check for autofix log files

If NOT run yet:

If the project is in git, record a baseline first: run `git stash create` and note the SHA (use `HEAD` if it prints nothing), and note the output of `git status --porcelain`.

Prompt the user to run [dbt-autofix](https://github.com/dbt-labs/dbt-autofix) (a first-party tool maintained by dbt Labs that automatically fixes common deprecation patterns):

uvx --from git+https://github.com/dbt-labs/dbt-autofix.git dbt-autofix deprecations

**Important**: Wait for autofix to complete before proceeding with classification.

Understand autofix changes (CRITICAL):

Before analyzing any migration errors, you MUST understand what autofix changed:

1. **Review the git diff** (if project is in git):

• Baseline recorded before autofix: `git diff <baseline-sha>`. New `??` entries in `git status --porcelain` are files autofix created.
• Autofix already committed: `git