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 local 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 Copilot features. Refer to Enable dbt Copilot.

 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: execute_sql requires a Personal Access Token (PAT). Service tokens do not work for this tool.

Solution:

  1. Generate a Personal Access Token (PAT) in Account settings → API tokens → Personal tokens.
  2. Use the PAT as your DBT_TOKEN value.
  3. Also ensure DBT_DEV_ENV_ID and DBT_USER_ID are set — these are required for execute_sql.
 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