fix(slack): surface attachment access diagnostics#16206
Merged
Conversation
Translate Slack attachment failures into actionable user-facing notices
instead of generic download errors. When a scope/auth/permission issue
breaks attachment processing, the user sees:
[Slack attachment notice]
- Slack attachment access failed for photo.jpg. Missing scope:
files:read. Update the Slack app scopes/settings and reinstall
the app to the workspace.
Two helpers do the translation:
_describe_slack_api_error — handles SlackApiError responses
(missing_scope, invalid_auth, file_not_found, access_denied, etc.)
_describe_slack_download_failure — handles httpx.HTTPStatusError
(401/403/404) and Slack-returns-HTML-sign-in fallbacks
Wired into three existing call sites:
- the Slack Connect files.info path (PR #11111) so scope errors
surface instead of being logged as generic "files.info failed"
- the image, audio, and document download paths so 401/403 and
HTML-body responses translate into actionable notices
Adjustment from original PR: dropped _probe_slack_file_access_issue,
the proactive pre-download files.info probe. It added one extra
Slack API call per attachment even on healthy ones, and overlapped
with the existing files.info call from PR #11111. The post-failure
translation path covers the same user-facing diagnostic value
without the per-message tax.
Also documents files:read scope more prominently in the Slack setup
guide and troubleshooting table.
Contributed back from https://github.com/xinbenlv/zn-hermes-agent.
Closes #7015.
Co-authored-by: xinbenlv <zzn+pa@zzn.im>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Translate Slack attachment failures (missing_scope, invalid_auth, 401/403/404, HTML sign-in page) into actionable user-facing notices so the agent can tell the user what to fix, instead of logging a generic 'download failed' and going silent.
Changes
gateway/platforms/slack.py: two helpers —_describe_slack_api_error(SlackApiError response → text) and_describe_slack_download_failure(httpx/generic exception → text). Wired into the Slack Connectfiles.infopath (from PR fix(slack): get files in Slack Connect channel #11111) and the image/audio/document download failure paths. When any of them translates an error, the notice is prepended to the inbound message text as[Slack attachment notice]so the agent sees it.website/docs/user-guide/messaging/slack.md:files:readadded to troubleshooting table + missing-scopes caution block mentions it.Adjustment from original PR
Dropped
_probe_slack_file_access_issue— the original PR added a proactivefiles.infocall before every download attempt, even for healthy attachments. That's one extra Slack API round-trip per file per message. The post-failure translation path delivers the same user-facing diagnostic value without the per-message tax. (The helper method was also dead once the probe was removed, so_get_team_clientwent with it.)Validation
tests/gateway/test_media_download_retry.py+tests/gateway/test_slack.py: 174 passed (3x green).Credits
Closes #7015