Semantic Layer / execute_sql tools fail with unhelpful error when dbt platform's Snowflake credentials expire

[b-per]

Summary

When using MCP tools that execute queries against the warehouse via the dbt platform (i.e. query_metrics and execute_sql), if the platform's Snowflake credentials have expired, the tool returns a cryptic error message like:

SSO authentication has expired, please re-connect to Snowflake: https://docs.getdbt.com/faqs/Troubleshooting/refresh-snowflake-oauth-credentials

This error message is misleading and sends users down the wrong troubleshooting path.

Two distinct auth scenarios

It's important to distinguish between two different authentication failure modes in dbt-mcp:

1. Local machine → Snowflake (dbt CLI tools)

Applies to tools that run dbt commands locally (build, run, show, etc.). Authentication is between the local machine and Snowflake — typically browser-based SSO (externalbrowser). Already tracked in #628.

Resolution: Re-authenticate locally (e.g. run dbt debug to trigger a browser login).

2. dbt platform → Snowflake (warehouse-executing platform tools)

Applies to tools that send queries to the warehouse through the dbt platform: query_metrics and execute_sql. The local machine is not involved — the MCP server forwards the query to the dbt platform, which executes it against Snowflake using its own stored development credentials.

Resolution: The user must go to the dbt Cloud UI → Profile → Credentials and refresh their development environment credentials for the relevant project/environment. There is nothing to fix locally.

Problem

The current error message points users toward local Snowflake reconnection steps (re-authenticate in the browser), which does not resolve the issue when the problem is actually expired credentials on the dbt platform side.

Expected behavior

When query_metrics or execute_sql fail due to expired platform credentials, the error should:

1. Clearly indicate this is a dbt platform credential expiry, not a local auth issue
2. Direct the user to refresh their development credentials in the dbt Cloud UI

Steps to reproduce

1. Configure dbt-mcp with Semantic Layer or SQL tools enabled
2. Let the dbt platform's Snowflake development credentials expire (or set up a fresh environment where they haven't been configured)
3. Call query_metrics or execute_sql
4. Observe the misleading error message

[psaikaushik]

Hi @b-per 👋 — I'd like to work on this issue.

Understanding of the problem:
When query_metrics or execute_sql fail due to expired dbt Cloud platform credentials (scenario 2 in the issue), the error message incorrectly directs users to re-authenticate locally, which doesn't resolve the platform-side credential expiry.

Proposed approach:

1. Identify the error handling paths in query_metrics and execute_sql tools where Snowflake SSO/credential errors surface
2. Add detection logic to distinguish between:
   • Local → Warehouse auth failures (already tracked in dbt CLI commands fail when warehouse token expires with browser-based authentication #628)
   • dbt Platform → Warehouse auth failures (this issue)
3. For platform credential expiry errors, return a clear message like:

   "Your dbt Cloud development credentials have expired. Please refresh them in the dbt Cloud UI: Profile → Credentials → [project/environment]. This is a platform-side credential issue, not a local authentication problem."

4. Add unit tests for the new error classification and messaging

I'll review the Semantic Layer tool implementations and error handling flow to map the exact code paths. Happy to discuss the approach further.

Could you assign this to me? Thanks!

[psaikaushik]

PR submitted: #714

The fix adds regex-based detection for common platform credential expiry patterns (SSO expired, OAuth token expired, etc.) in _format_semantic_layer_error() and appends a clear hint directing users to refresh credentials in the dbt Cloud UI. Includes 15 unit tests covering positive matches, negative cases, and integration with the existing error formatting pipeline.

[jairus-m]

SSO authentication has expired, please re-connect to Snowflake: https://docs.getdbt.com/faqs/Troubleshooting/refresh-snowflake-oauth-credentials

For running query_metrics and execute_sql with expired Snowflake credentials, I think this error message and provided link does actually lead to the correct debugging path.

Because if you follow the link you get instructions to:

1. Go to your Profile settings page, accessible from the navigation menu.
2. Navigate to Credentials and then choose the project where you're experiencing the issue.
3. Under Development credentials, click the Reconnect Snowflake Account button. This will guide you through re-authenticating using your SSO workflow.

These are the correct steps to address the 2nd issue "dbt platform → Snowflake (warehouse-executing platform tools)" that @b-per identified:

The user must go to the dbt Cloud UI → Profile → Credentials and refresh their development environment credentials for the relevant project/environment. There is nothing to fix locally.

So if we get the above message + link in an error, I think it would be helpful. The current PR is based off parsing regex patterns off that original error message posted in this issue. I'm not sure if that's helpful in its current state as it would be redundant.

However, in the community slack and in my own experience, I have come across more cryptic messages like:

Credentials provided has expired. Please reauth with your auth provider.

This is an error message that is actually vague and can be interpreted as either auth failure scenario 1 or 2. Given this, I'd personally suggest (if possible), to identify the existing error strings that are genuinely ambiguous/cryptic. The example error in this issue which the PR is based off of is actually fairly helpful.

Thoughts? @psaikaushik - I think your approach makes sense, just need to dial in a bit on the pattern matching part