Skip to main content

MCP troubleshooting

This page consolidates troubleshooting steps for all dbt MCP setups. For specific troubleshooting steps for your AI client, see the troubleshooting sections in the Get started and Setup and config pages.

 Can't find the uvx executable

Symptoms: Error messages like Could not connect to MCP server dbt-mcp, Error: spawn uvx ENOENT, or spawn uvx ENOENT in your MCP client.

Cause: Your MCP client (like Claude desktop) can't find uvx in its PATH because it starts with a limited environment.

Solution: Use the full path to uvx in your configuration.

  1. Find the full path:

    • macOS/Linux: Run which uvx in Terminal.
    • Windows: Run where uvx in Command Prompt or PowerShell.

  2. Replace "command": "uvx" with the full path:

{
  "mcpServers": {
    "dbt": {
      "command": "/full/path/to/uvx",
      "args": ["dbt-mcp"],
      "env": { }
    }
  }
}

Example on macOS with Homebrew: "command": "/opt/homebrew/bin/uvx"

For VS Code (mcp.json), the same fix applies — replace uvx with its full path in the command field.

 OAuth login not initiating

Symptoms: The OAuth browser window never opens, or authentication appears to hang.

Cause: dbt MCP uses a lock file to avoid repeated authentication. If a previous session left the lock file in place, it can block new authentication attempts.

Solution:

  1. Close your MCP client (Claude Desktop, Cursor, VS Code, etc.).
  2. Delete the self-hosted dbt MCP config files:
    • macOS/Linux: rm -f ~/.dbt/mcp.yml ~/.dbt/mcp.lock
    • Windows: Remove-Item -Force $env:USERPROFILE\.dbt\mcp.yml, $env:USERPROFILE\.dbt\mcp.lock
  3. Restart your client and try connecting again.

If these steps don't resolve the issue, confirm that AI features are enabled on your account. An account admin can enable them in Account settings → Edit → toggle on Enable account access to dbt Wizard features. Refer to Enable dbt Wizard.

 Server not starting

Symptoms: The MCP server shows as disconnected or unavailable in your client.

Diagnosis: Check the server logs:

  • VS Code: Open the Command Palette (Ctrl/Cmd + Shift + P) → MCP: List Servers → click the dbt server to see detailed logs.
  • Claude Desktop: Check ~/Library/Logs/Claude (macOS) or %APPDATA%\Claude\logs (Windows).
  • All clients: Set DBT_MCP_LOG_LEVEL=DEBUG in your environment variables to get more verbose output.

Common causes:

  • Missing or incorrect DBT_PROJECT_DIR or DBT_PATH — verify the paths exist and are absolute paths.
  • Invalid or expired authentication tokens — generate a new token and update your config.
  • Missing required environment variables for the toolset you're trying to use — see Tool requirements.
 Configuration not working in WSL (VS Code)

Symptoms: VS Code MCP config works on other machines or native Windows but not in WSL.

Cause: Local user settings are not applied in WSL environments.

Solution:

Configure MCP in the WSL-specific settings instead of local user settings:

  1. Open the Command Palette → Preferences: Open Remote Settings.
  2. Or select the Remote tab in the Settings editor.
  3. Add your MCP server configuration there.
 execute_sql tool not working

Symptoms: The execute_sql tool returns an authentication error or is unavailable.

Cause: How you fix this depends on how you connected:

  • Remote MCP with OAuth: Sign in through your MCP client when prompted. You don't need a personal access token.
  • Remote MCP with token-based auth: You need a personal access token (PAT). Service tokens won't work. You also need x-dbt-dev-environment-id and x-dbt-user-id headers. The user ID must match the user who created the PAT.
  • Local MCP: Set DBT_TOKEN to a personal access token (PAT). Service tokens won't work.

Solution:

  1. If you use OAuth for remote MCP, confirm you completed sign-in and consent in your MCP client.
  2. If you use token-based auth or local MCP, create a personal access token (PAT) in Account settings → API tokens → Personal tokens.
  3. For token-based remote MCP, add the PAT to the Authorization header as Token YOUR_PAT. For local MCP, set the PAT as your DBT_TOKEN value.
  4. Also ensure DBT_DEV_ENV_ID and DBT_USER_ID are set (local MCP) or x-dbt-dev-environment-id and x-dbt-user-id headers are set (remote MCP). Refer to Finding your IDs for details.
 Toolset unavailable or showing as disabled

Symptoms: A toolset (Semantic Layer, Discovery, Admin API) is not available in your AI client even though you've configured credentials.

Cause: Either the required variables are missing, or the toolset has been explicitly disabled.

Solution:

  1. Check that all required variables for the toolset are set — see Tool requirements.
  2. Check whether you have any DISABLE_* variables set to true that might be turning off the toolset.
  3. If you're using enable mode (DBT_MCP_ENABLE_*), make sure the toolset you need is listed.
  4. Set DBT_MCP_LOG_LEVEL=DEBUG to see which toolsets are active at startup.
 Pasting full URLs instead of IDs

Symptoms: Authentication errors, unexpected behavior, or the server failing to connect to the right environment.

Cause: Environment variables like DBT_PROD_ENV_ID, DBT_USER_ID, and DBT_ACCOUNT_ID expect numeric integers, not full browser URLs.

Solution:

# ✅ Correct
DBT_HOST=cloud.getdbt.com            # https://cloud.getdbt.com also works
DBT_PROD_ENV_ID=54321
DBT_USER_ID=123

# ❌ Wrong — IDs must be numeric, not full URLs
DBT_PROD_ENV_ID=https://cloud.getdbt.com/deploy/12345/projects/67890/environments/54321
DBT_USER_ID=https://cloud.getdbt.com/settings/profile

See Finding your IDs for step-by-step instructions.

 Multi-cell or static subdomain account connection issues

Symptoms: Connection errors when your account URL includes a prefix (for example, abc123.us1.dbt.com).

Solution (as of v1.14.0): Set DBT_HOST to the full hostname including the prefix. If you're using PAT-based auth, also set DBT_ACCOUNT_ID.

# ✅ Correct
DBT_HOST=abc123.us1.dbt.com
DBT_ACCOUNT_ID=12345  # required for PAT-based auth

You no longer need to set MULTICELL_ACCOUNT_PREFIX or DBT_HOST_PREFIX. If you have these set from an older configuration, remove them.

Was this page helpful?

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.

0