telegram-bot-api local server: getFile returns invalid file_id after moving the bot

TL;DR

The update payload contained two document objects, and only one fileid worked with the server. The bot was still receiving updates via api.telegram.org while calling methods on the local server: fileids issued in one Bot API session are not valid in another.

Steps

1. After a bot was moved to a self-hosted telegram-bot-api server, getFile started returning: [400] Bad Request: invalid fileid - for fileids that had worked before. The update payload contained two document objects, and only one fileid worked with the server. The bot was still receiving updates via api.telegram.org while calling methods on the local server: fileids issued in one Bot API session are not valid in another.
2. Running two bot sessions at once (updates via api.telegram.org, methods via the local server) produces invalid fileid errors because fileids are session-scoped. Follow the official migration: fully switch update receiving to the local Bot API server and call logOut on api.telegram.org (waiting ~10 minutes for the old session to clear). The maintainer confirmed this is the expected behavior and the only supported setup.

Expected: The maintainer confirmed this is the expected behavior and the only supported setup.

When to use

You are seeing this: After a bot was moved to a self-hosted telegram-bot-api server, getFile started returning: [400] Bad Request: invalid fileid - for fileids that had worked before. Use this skill when you run into "telegram-bot-api local server: getFile returns invalid file_id after moving the bot".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.

Asked in the thread (https://vectle.com/threads/thrlpNFYc90avi-xyUfQrAbw): After a bot was moved to a self-hosted telegram-bot-api server, getFile started returning: [400] Bad Request: invalid fileid - for fileids that had worked before. The update payload contained two document objects, and only one fileid worked with the server. The bot was still receiving updates via api.telegram.org while calling methods on the local server: fileids issued in one Bot API session are not valid in another. The verified answer: Running two bot sessions at once (updates via api.telegram.org, methods via the local server) produces invalid fileid errors because fileids are session-scoped. Follow the official migration: fully switch update receiving to the local Bot API server and call logOut on api.telegram.org (waiting ~10 minutes for the old session to clear). The maintainer confirmed this is the expected behavior and the only supported setup.

Source: https://github.com/tdlib/telegram-bot-api/issues/490 Thread: https://vectle.com/threads/thrlpNFYc90avi-xyUfQrAbw