🚨 Slack Error: 'file_not_found' — Cause, Fix, and Troubleshooting Guide

Overview

file_not_found means the file id you passed doesn’t resolve to a file this token can see. The id may be wrong, the file may be deleted, or it may belong to another workspace or an upload that never completed.

{
    "ok": false,
    "error": "file_not_found"
}

It appears on files.info, files.delete, files.sharedPublicURL, and on chat.update/message calls that reference a file id.

Symptoms

• A file id that worked earlier now fails (deleted or expired).
• files.info returns file_not_found for the exact id you stored.
• The id came from a different workspace or a different app’s upload.

Common Root Causes

1. The file was deleted

Deleting a file removes it entirely; any later reference returns file_not_found (or file_deleted).

2. Wrong or truncated file id

A typo, a clipped id, or confusing a file id with a message ts fails to resolve.

3. Incomplete upload

With the current flow, if files.completeUploadExternal never ran, the upload id doesn’t become a real file.

4. Cross-workspace / wrong-token reference

File ids are workspace-scoped; a token from another workspace can’t see the file.

How to diagnose

Probe the id directly:

curl -s "https://slack.com/api/files.info?file=F0FILE0001" \
  -H "Authorization: Bearer $SLACK_BOT_TOKEN"

{"ok": false, "error": "file_not_found"}

Confirm the token’s workspace matches where the file was uploaded:

curl -s https://slack.com/api/auth.test \
  -H "Authorization: Bearer $SLACK_BOT_TOKEN"

Fixes

• Verify the id with files.info before referencing it elsewhere; store the canonical F… id, not a URL fragment.
• Re-upload if deleted using files.getUploadURLExternal → PUT bytes → files.completeUploadExternal, and always run the completion step.
• Match the workspace: reference files only with a token from the same workspace that owns them.
• Handle deletion gracefully: treat file_not_found on a cleanup path as “already gone” rather than an error to retry.

What to watch out for

• file_not_found vs file_deleted/file_is_deleted: some methods distinguish “never existed / not visible” from “existed and was deleted” — handle both as non-retryable.
• The legacy files.upload endpoint is deprecated; if you still call it you may also see method_deprecated. Move to the external-upload flow.
• Don’t persist Slack file URLs as identifiers — persist the F… id, which is stable and queryable.

Related

• Slack Error: ‘message_not_found’
• Slack Error: ‘too_many_attachments’
• Sharing files and snippets from Slack ops bots