[ADAP-921] [Feature] Improve auth-related error messages to include troubleshooting guidance

[mirnawong1]

Is this your first time submitting a feature request?

• [X] I have read the expectations for open source contributors
• [X] I have searched the existing issues, and I could not find an existing issue for this feature
• [X] I am requesting a straightforward extension of existing dbt-snowflake functionality, rather than a Big Idea better suited to a discussion

Describe the feature

When users using dbt encounter a Could not deserialize key data... or JWT token error message when trying to set up their key/pair authentication, the error message doesn't provide or link to known solutions for this error.

Can the error message include a link to this page/section so users can self-serve and unblock themselves?

update - per Doug's suggestion, it's better to use the language from that troubleshooting section and add it directly within the error message instead. this way, if the link ever changes, the user won't get a 404 error, etc.

Describe alternatives you've considered

No response

Who will this benefit?

all users authenticating via key/pair and encountering this error (which is common)

Are you interested in contributing this feature?

Yes

Anything else?

https://docs.getdbt.com/docs/cloud/connect-data-platform/connect-snowflake#troubleshooting

[dbeatty10]

Good idea @mirnawong1 !

The main drawback of hard-coding a link to the relevant documentation is that then the links on docs.getdbt.com could change, and we wouldn't have a way to know if the link within dbt-snowflake (or dbt-core) is out-of-date.

What if we used the language from that troubleshooting section and added it directly within the error message instead?

i.e., catch the error and then re-raise it like this:

Error: Could not deserialize key data

This could be because of mistakes with your {insert description here} key like not copying correctly, missing dashes, or leaving out commented lines.

or:

Error: JWT token

One possibility is that the public key was not entered correctly within Snowflake. You can reach out to Snowflake for help or refer to Snowflake documentation on this error for more info by searching for 'Key Based Authentication Failed with "JWT token is invalid" Error'.

This could also be a transient issue between Snowflake and dbt. When connecting to Snowflake, dbt gets a JWT token valid for only 60 seconds. If there's no response from Snowflake within this time, you might see a JWT token is invalid error.

[mirnawong1]

that's a great suggestion @dbeatty10 ! i'd love to help if it's possible or needed!

i think the redirects would catch the docs link change but either way, having the instructions directly in the error is helpful. would this also be presented in a nice UX-way in dbt cloud?

[dbeatty10]

The main problem with redirects is that we'd often want to use URLs that include anchors (like #troubleshooting), and I'm not aware of a way within the code for docs.getdbt.com that we can do redirects for anchors. Even if we could do it, it also would rely on people remembering to create those redirects.

So having problem-solving instructions directly in the error is probably the best of all worlds.

Agreed that we'd want the error message to be written in such a way that the UX looks nice in dbt cloud also.

[mirnawong1]

hey @dbeatty10 ! you're so right about the anchor links! sounds good to me and thanks for your suggestion - I'll update my description above but it's better to include the solution in the error message so users understand what to do right then and there 🙏

[github-actions[bot]]

This issue has been marked as Stale because it has been open for 180 days with no activity. If you would like the issue to remain open, please comment on the issue or else it will be closed in 7 days.