The short answer
- 1File references have a limited lifetime; the expiry error is part of the normal flow.
- 2Refetch the message, profile, sticker set or story the file came from.
- 3Store each file's current reference and its origin.
In this article
What a file reference is
In the Telegram API, information about a photo or document comes with a byte value called a file reference (file_reference) as well as the file's ID. To download the file you must present this reference. References have a limited lifetime, so a request with one you stored long ago is refused. The point is that file information you saw once cannot be used forever.
The errors you get when it expires
| Error | Meaning |
|---|---|
FILE_REFERENCE_EXPIRED | The reference's lifetime is over |
FILE_REFERENCE_INVALID and similar | The reference does not match; handle it the same way, with a fresh one |
This error is not a bug; it is part of the normal flow. Fetch again the place where the file originally appeared, take the new reference from it, and repeat the same request.
Where to fetch it again
| Where the file came from | How to get a fresh reference |
|---|---|
| A message in a chat | Fetch that message again: messages.getMessages for ordinary chats, channels.getMessages for channels |
| A user's profile photo | Fetch that user's photo list again |
| A sticker | Fetch that sticker set again |
| A wallpaper or theme | Fetch that wallpaper or theme again |
| A story | Fetch that story again |
Store data so you are ready for it
The official documentation advises apps that keep files around for a long time to store two things:
- File ID → current reference: replace it every time a new reference arrives.
- File ID → where the file came from (which message in which chat, for example): when the error comes, look here and fetch the original place again.
With both stored, an expired reference can be renewed automatically and the download continues without the user noticing anything.
The rules for downloading in parts are in uploading and downloading files, and other errors in reading API errors.
FAQ
What causes FILE_REFERENCE_EXPIRED?
The file reference you sent is too old. References expire by design.
How do I get a new file reference?
Fetch the original source again, such as the message with messages.getMessages or channels.getMessages, and use the reference it contains.
Does the Bot API have file reference errors?
No. Bot API file_id values are a separate system that a bot can reuse.
Sources
At a glance
- 1Why
References stop old file information being used forever.
- 2Fix
Refetch the original place, take the new reference, retry.
- 3Prepare
Keep file ID → reference and file ID → origin.
Updated
