`files_upload_v2`: `alt_txt` parameter causes silent failure when sharing files to channels

[quacktorai]

Description

When using files_upload_v2 with the alt_txt field in file_uploads, files are uploaded successfully but silently fail to be shared to the specified channel. Removing alt_txt resolves the issue.

Environment

• slack-sdk version: 3.39.0
• Python version: 3.12
• OS: Xubuntu 24.04.3 LTS

Steps to Reproduce

from slack_sdk import WebClient

slack_client = WebClient(token="xoxb-...")

# Read PDF file content
with open("report.pdf", "rb") as f:
    pdf_content = f.read()

# Attempt to upload with alt_txt
files_to_upload = [{
    "content": pdf_content,
    "filename": "report.pdf",
    "title": "Test Report",
    "alt_txt": "Content of the Test Report for model version 1.0.0",  # This causes the issue
}]

response = slack_client.files_upload_v2(
    channels=["XXXXXXXXXXX"],  # Valid channel ID where bot is a member
    file_uploads=files_to_upload,
    initial_comment="Test upload with alt_txt"
)

print(response)

Expected Behavior

• Files should be uploaded AND shared to the specified channel
• The initial_comment message should appear in the channel
• Response should include the files with populated shares, channels fields

Actual Behavior

• Files are uploaded successfully (response['ok'] is True)
• Files are NOT shared to the channel (no message appears)
• Response shows empty sharing fields:

'shares': {}
  'channels': []
  'groups': []
  'ims': []

• The bot CAN post messages to the channel using chat_postMessage with the same channel ID
• No error is raised, making the issue difficult to debug

Workaround

Remove the alt_txt field from file_uploads:

files_to_upload = [{
    "content": pdf_content,
    "filename": "report.pdf",
    "title": "Test Report",
    # "alt_txt": "...",  # REMOVED - causes silent failure
}]

response = slack_client.files_upload_v2(
    channels=["XXXXXXXXXXX"],
    file_uploads=files_to_upload,
    initial_comment="Test upload without alt_txt"
)

With this change, files are successfully shared to the channel.

Additional Context

• Tested with both channel= and channels=[] parameters - both exhibit the same issue when alt_txt is present
• The issue appears to be specific to the files.completeUploadExternal step in the files_upload_v2 workflow
• alt_txt is documented in the SDK's FileUploadTypeDef as an optional field for accessibility (screen readers)
• This may be related to PDF files specifically (not tested with other file types)

Questions

1. Is alt_txt fully supported in the v2 file upload API (files.completeUploadExternal)?
2. Should there be validation or a warning when alt_txt causes sharing to fail?
3. Is this a known limitation with certain file types (PDFs)?

Impact

This issue makes it difficult to create accessible file uploads with proper alt text for screen readers when using the v2 upload API. The silent failure mode also makes debugging extremely challenging.

[zimeg]

Hey @quacktorai! 👋 Thanks for sharing this finding with us!

I can confirm for certain filetypes the alt_txt argument causes uploaded files to not appear in channel - this was tested with similar plain text files.

However for images the alt_txt value appears with the uploaded image I find, which might align with documentation:

alt_txt

Description of image for screen-reader.

🔗 https://docs.slack.dev/reference/methods/files.getUploadURLExternal

A silent error isn't great for other filetypes and I'll raise this with the team, but I'd recommend removing alt_text from upload text or PDF files in favor of a well-worded initial_comment value for now 👾