fix: improve error messages for platform credential expiry in Semantic Layer tools

[psaikaushik]

Summary

When query_metrics or execute_sql fail due to expired dbt Cloud platform credentials, the error message currently points users toward local Snowflake re-authentication steps — which is misleading and sends them down the wrong troubleshooting path.

This PR adds detection for platform credential expiry errors and appends a clear, actionable hint directing users to refresh their credentials in the dbt Cloud UI.

Closes #670

What Changed

src/dbt_mcp/semantic_layer/client.py

• Added _PLATFORM_CREDENTIAL_ERROR_PATTERNS — a list of compiled regex patterns that match common credential expiry messages from Snowflake/data platforms (SSO expired, OAuth token expired, etc.)
• Added _PLATFORM_CREDENTIAL_HINT — a clear, actionable message explaining this is a platform-side credential issue and directing users to dbt Cloud UI → Profile → Credentials
• Added _is_platform_credential_error() — a helper that checks an error string against all known patterns
• Updated _format_semantic_layer_error() — now detects platform credential errors and appends the hint, while preserving the original error message and all existing formatting behavior

tests/unit/semantic_layer/test_platform_credential_errors.py

• 10 tests for _is_platform_credential_error() — covers all known patterns, case insensitivity, and negative cases (generic errors, syntax errors, timeouts, empty strings)
• 5 tests for _format_semantic_layer_error() — verifies the hint is appended for credential errors, preserved for QueryFailedError wrappers, and not added for generic errors

Why

Users on dbt Cloud with Snowflake SSO credentials that expire see this error:

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

This sends them to local re-authentication docs, which doesn't fix the problem. The actual fix is to refresh development credentials in the dbt Cloud UI. This PR makes that distinction clear.

Test plan

• All new unit tests pass (15 tests)
• No changes to existing test behavior — the original _format_semantic_layer_error logic is untouched; the hint is additive
• Manual verification with expired Snowflake credentials on dbt Cloud

Checklist

• I have performed a self-review of my code
• I have added tests that prove my fix is effective
• New and existing unit tests pass locally with my changes
• Changelog entry added

[psaikaushik]

@jairus-m thanks for merging #715! When you get a chance, this one is ready for review as well. Just rebased it onto latest main. Let me know if anything needs changing.

[jairus-m]

@psaikaushik hello pls make sure to address the same baseline comments I made from your other PR - signed commits, change log issue, etc. In the meantime as well, would love to see validation / screenshots of your fixes! (before and after as this update ). That would be very helpful 🙏

[psaikaushik]

@jairus-m : Just created another commit fixing all of them. Sorry about that. It skipped my mind. Thanks for your help! Regarding the test, I mocked the credentials expiration

Before

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

After

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

Hint: This error indicates that your dbt Cloud development credentials have expired. This is a dbt Cloud platform credential issue, not a local authentication problem.
To fix this, go to the dbt Cloud UI → Profile → Credentials and refresh your development environment credentials for the relevant project.
See: https://docs.getdbt.com/docs/dbt-cloud-environments/develop-in-the-cloud#access-the-cloud-ide

Please take a look. thanks!

[psaikaushik]

@jairus-m : Gentle reminder on the review. All the comments are addressed. Please take a look whenever you are free. thanks!

[jairus-m]

Hey @psaikaushik totally, thank you for the friendly reminder. I have this PR in mind and it's absolutely in my "todo" queue. As you know, plates get full - thank you for your patience. 🙏 Pls hang tight.

[jairus-m]

Hey @psaikaushik I'm trying to checkout your branch and merge the latest changes from main. There are conflicts. I'm trying to make changes but I do not think you allow maintainers to edit your branch.

Can you update your branch and address the conflicts? Or allow me to push the merge to main?

[psaikaushik]

Hey @psaikaushik I'm trying to checkout your branch and merge the latest changes from main. There are conflicts. I'm trying to make changes but I do not think you allow maintainers to edit your branch.

Can you update your branch and address the conflicts? Or allow me to push the merge to main?

@jairus-m : Sorry about that. Just gave permissions on the PR to be editable by the maintainers. I am also trying to rebase on my side but did that so that it's easier for you. Please take a look. thanks!

[jairus-m]

Left a comment related to these lines in the issue. Let me know what you think! We can continue that convo there for now.