/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

By default this skill uses `dbt compile` to reproduce and validate errors. The command can be customized:

• If the user specifies a different command (e.g. `dbt build`, `dbt test --select tag:my_tag`), use that instead
• If a `repro_command.txt` file exists in the project root, use the command from that file

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:

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):

   git diff HEAD~1

2. **Read autofix logs** (if available):

• Look for autofix output files
• Check terminal output saved by user
• Understand which files were modified and why

3. **Key things to look for**:

• Which patterns did autofix apply?
• What config keys were moved to `meta:`?
• What YAML structures changed?
• What Jinja modifications were made?
• Were any package versions updated? (autofix upgrades packages that require it)

**Why this matters**: Some migration errors may be CAUSED by autofix bugs or incorrect transformations. Understanding what autofix changed helps you:

• Identify if a current error was introduced by autofix
• Revert autofix changes if they caused new issues
• Avoid suggesting fixes that conflict with autofix changes
• Know which patterns autofix already attempted (don't duplicate)

If autofix caused issues:

• Document which autofix change caused the problem
• Consider reverting that specific change
• Report the autofix bug pattern for future reference

**Do not proceed with classification until you understand autofix's changes.**

Step 2: Classify Errors

Use the 4-category framework to triage errors. For the full patter