Handling Bugs and Troubleshooting

This manual is intended for volunteers of the TSF, but anyone else is free to take a look as well.

Every now and then users will report bugs in Telegram. The step-by-step guide and troubleshooting tips on this page will help you deal with those reports in style and eventually help Telegram get rid of the bugs themselves.

See the Bug Hunting Algorithm for tips on investigating new issues.

Reporting a bug

1. Search known issues

We use Trello boards to keep track of bugs (sorry, these boards are TSF-only, here's how you join), features and user suggestions, so your first stop when encoutering a bug report is Trello search. Most likely, we already know about the issue — sometimes it is not a bug at all. So make sure you study all the relevant cards.

If you have found the issue on Trello, leave a comment in the card with your user's #tq tag and device info (skip this step if the card already has too many comments of that kind and a ‘trending’ tag). Then go right to step 4.

Trello cards are organized in lists that are pretty self-explanatory:

  • Every card begins its journey in the ‘Unsorted’ list.
  • Once the issue was reviewed by a bug herder and reported to the developer, it moves to the ‘Reviewed & Reported’ list. Once this has happened, all we can do is wait and report any new occurrences in the comments (don't forget the #tq tags).
  • Finally, at some point, the card reaches ‘Fixed’ status, is declared a ‘Feature’ (this is how we want this to work), or ‘Not our bug’ (platform restrictions, etc.).

We also use some labels:

Orange — Our developers are fully aware of this issue and will or will not fix it eventually.
Purple — This issue will be fixed in the upcoming public release and is already fixed in the beta version.
Black — This is a frequent issue, we're getting many complaints about it.
Red — This card is no longer needed and is scheduled for deletion.

2. Investigate the bug

IMPORTANT: Please see the Bug Hunting Algorithm after this manual for an in-depth look at investigating bugs.

If you can't find anything useful on Trello:

  1. Check app version. Must be the latest available.
  2. Try to reproduce the bug, if you have a relevant device on hand. Ask your local group if you don‘t – don’t forget to include all hashtags from the user's footer with your question.
  3. Check the Troubleshooting Tips below, there are some useful tips for identifying and reporting common issues.
  4. All support questions have device, system, app type and version data attached below the message. If this attachment is not there, it means that Telegram can’t use notifications on the user’s device.
  5. Find and ask the right questions that would allow us to locate the bug — in as few steps as possible. We have a separate and rather exciting manual on this topic, known as the Bug Hunting Algorithm.
  6. E.g., if a user can't playback a voice message — the problem may be in the file itself, in the recording app, in the receiving app, on the recording device, etc. We need to ask the right questions if we want this to be quick.

Reporting a bug is in many regards like convicting the developer of a crime. Just as in that case, you need a clear vision of what happened and why, hard evidence (screenshots) and witnesses (users). Unlike in a criminal case, though, it is considered appropriate and even necessary to reproduce the deed (see if you can reproduce the bug and get the same results).

Another crucial difference: our defendant is also the judge. He is accountable, of course, but still biased. It is in the developer‘s best interest to convince you and the public that the bug is not related to his work. Server-side devs will blame the client devs, client devs will blame the server-side devs — and they all together will blame the OS and device manufacturers. While sometimes this is true, we need to leave no escape for them if it isn’t. Blury bowl of berries

3. Report the bug

If the bug is not mentioned on the Issues board and the Troubleshooting manual doesn't have any special instructions for the case, we need to report it on Trello.

  1. Make sure you've really completed steps 1 and 2 of this guide.
  2. Important: Discuss the issue in your local group — you never know what your teammates may have to say. Maybe there's no need to create a card and an existing one needs editing instead.
  3. If you're sure this is necessary, add the issue to the board. Make sure your heading has all the relevant info.
  4. Start with a short description (~200 chars), then add more info in the long description field.
  5. Always add the user's (or your own if you have the issue) footer with the system hashtags.
  6. Add relevant screenshots to the issue. This is optional if the issue is clear enough without them.
  7. Make sure that your description has all the relevant keywords, so that it's easy to find the issue via search.
  8. When you add your first issue to Trello send the link to Markus — along with a picture of a beetle.
  9. Think of the words you would use if you were looking for that issue — try them in the searchbox. Adjust the description accordingly.
  10. Ask your teammates if you have any doubts.
Labels and Comments

A new issue should have no labels at first. It can only become ‘confirmed by devs’ when one of the developers has seen it — better leave labelling to them.

  • Please don‘t touch the labels unless you’re 200% sure you know what you're doing.
  • Add a comment whenever a bug's status is changed.
  • Discuss in the regional groups, comments are for important updates to the bug only.
  • Make sure the bug's description covers all the important info that emerged in the comments.

4. Notify the user

Once we‘re done, we need to get back to the user and tell him that we’ve located the issue or are investigating it. You never know how long that might take, but the user must know that he succeeded in alerting us — and helped us greatly.

  • Always include an issue ID hashtag in your reply in this situation.
  • All trello cards have unique identifiers (open card, click on “share and more”, then ‘link to this card’, take the last part or the link, after /c/ — e.g. ikGVrA1X).
  • We use this ID to create a hashtag (e.g. #issue_ikGVrA1X) and include it in our reply to the user with that problem. Like this, for example:

We are terribly sorry that you are not able to send out your GPS location via Telegram on iOS8. We reproduced it and are already working on a bug fix. Your issue #issue_xpdMFJhw has been recorded and we'll get back to you as soon as we have any news.

This allows us to use Telegram hashtag search to track issues for follow-up questions. The bot can use these hashtags to send automatic replies when a bug is fixed. We can also search for this issue on Trello by its ID.

5. Stick to our goal

  1. Our final goal in case of any bug is to create a report in Trello that would get the status confirmed by a developer or feature.
  2. If no report was created or no existing relevant report found — we did nothing, regardless of how much time we spent talking to the user and diagnosing the issue.

And remember that in order to achieve this goal with a clear conscience, we need to respect our users' time and effort — a little more on this below:

A note on users

One may think that users are people with problems. Wrong. It is us, who have problems — the user is just a convenient medium for studying them. Our problem is either that something is wrong in our system. Or that we can't understand what the user is doing wrong. When you look at it this way, you quickly realize that the user is our most important asset when it comes to bugs. He can help us identify bugs and improve usability.

So when somebody comes with a problem, we are not looking for a way to make him go away. Instead we must do all we can to not let the user leave before we find the problem. This means that everything you ask him to do must tell you something important. Nobody enjoys rebooting their phone or logging out and in. The general rule is minimum actions — maximum effect. Rabid bunnies alert

If you do ask something that requires at least some effort, please be nice about it! People don‘t have any obligations to Telegram — we need to convince them to help us and to thank them when they do. It’s the least we can do.

Now that we're done with the basic reporting process, below are some common issues and what you should do when somebody is complaining about similar stuff.

Troubleshooting common issues

This advanced troubleshooting guide is intended for volunteers of the Telegram Support Force.
Everyone else is also welcome to take a look. Help friends and loved ones — or troubleshoot yourself!

Can’t Install App

iOS: Device must run iOS 6 or higher.

- If SDK >= 14 —> Android version must be 4.x
- Ask whether other applications install ok
- If nothing helps we need to know the Android version and device model

Messages not getting delivered

The following cases cover pretty much all the complaints:

  • The user may be confused by the check system. In Telegram: 1 check = message sent, 2 checks = message read (opened by the recipient). So the sender may think the message is not getting delivered or is delivered slowly, while he is in fact waiting for it to be read.
  • The user may be blocked. When a user is blocked, he will not be notified in any way. His messages will just stop being read: one tick, always. He should ask his partner to check Settings — Blocked users. Blocked users don‘t see your online and last seen status and don’t see a person's profile picture.
  • The user may confuse messages and notifications and say that messages are not getting delivered, when he in fact means notification issues. If a person sees the message upon opening the app, but doesn't get notified until he opens the app — see notification problems.
  • Since people can delete messages for everyone after sending them, it could be that a user means notifications for messages that have already been deleted by the sender.
  • Lastly, when dealing with Secret Chats, users must remember, that messages will only be delivered to the device that was used when the Secret Chat was created.

In case it's none of these five (but it must be one of these five, really), this is one of the worst things that can ever happen in Telegram. We need to know:

  • Phone numbers for all participating users
  • Devices and app types for all users
  • Secret chats or cloud chats? Or both?
  • One-way or two-way problem?

Notification problems


  • Make sure notifications are on in Telegram AND in phone settings (Settings — Notification Center), check app version.
  • Make sure notifications weren’t disabled for a specific chat or group.
  • Shut down Telegram (go to home screen, double tap home button, kill Telegram (swipe upwards), then go to Phone Settings, set alert style for Telegram to NONE. Relaunch Telegram, go to Phone Settings, set alert style back to banners.

What we need to know if nothing helps:

  • User’s phone number
  • Type of problem (notifications: a. never come, b. come only sometimes)
  • Logs that capture the problem


We currently have two types of notifications on Android: GCM and our own custom notification service that is independent from Google. Note that Google notifications (GCM) just won‘t work properly on some Android devices. The Telegram notification service is reliable, but requires additional battery resources. It doesn’t and shouldn't take much though, so please report all drastic battery-draining cases immediately.

  • Make sure the latest app version is installed.
  • Make sure notifications weren’t disabled for a specific chat or group.
  • Turn on ‘Notification Service’ in Settings — Notifications and sounds.

NOTE: Huawei and Xiaomi devices have evil task killer services that interfere with the Telegram notification service. In order for our notifications to work, users need to add Telegram to allowed apps in those devices' security settings. Huawei: Phone Manager App > Protected apps > Add Telegram to the list. Xiaomi: Services > Security > Permissions > Autostart, find Telegram and enable autostart.

If the user does not want to use the Telegram Notification Service (in this case we cannot guarantee stable notifications) and has problems with GCM notifications:

In case you went through all the steps to no avail, we need to know:

  • User’s phone number
  • Type of problem (notifications: a. never come, b. come only sometimes)
  • Logs that capture the problem

Contact importing problems

User doesn’t see his contacts in Telegram. Or sees numbers instead of names in Messages list.

Important: Naturally, one of the easiest ways to solve this would be to save the number in international format. Do not advise this before other methods. Our systems must correctly parse any contacts. Therefore it is imperative to collect these samples and bring them to your local group so that we can adjust the algorithms.


  • Temporarily change the name of the missing contact in Phone Contacts (not in Telegram) — add a few symbols, then change back again
  • If that doesn’t help, relogin

Things we need to know if nothing helps:

  • User’s phone number
  • Phone number(s) of the contact(s)
  • How exactly these numbers are stored in users phone book (international format or anything else?)
  • Devices and app versions for all users


  • Relaunch the app (not relogin! that won’t help) — swipe the app off the currently-running-apps list
  • Temporarily change the name of the contact in phone contacts (add a few symbols, then change back again)

Things we need to know if nothing helps:

  • User’s phone number
  • Phone number(s) of the contact(s)
  • How exactly these numbers are stored in users phone book (international format or anything else?)
  • Devices and app versions for all users

Speed issues

Make sure that we're really talking about speed issues here. In Telegram, 1 check = message sent, 2 checks = message read (opened by the recipient).

What we need to know:

  • Problem occurs in one app only, or in all apps (e.g. an iPhone and Tdesktop on the same wifi)
  • Problem occurs when sending or receiving (uploading / downloading)? Or both?
  • What internet connection is being used? If wifi, advise user to try 3G and vice versa and see what changes.
  • Recipient and sender's phone numbers and/or #tq tags.
  • External IP address of the user for the device with the problem at the time of the problem.
  • Time of problem (better include the timezone too).
  • In case of a photo/video, ask the user to forward it to us. Not upload it again, just forward the original message with the attachment.

Connection issues

When people are reporting connection issues, check twitter first: are there any widespread problems. If the problem is local, we need to find out a lot of information before things can be investigated. Things to ask:

  • Do other (non-Telegram) apps work OK?
  • What exactly is happening? (always ‘connecting…’ / always ‘updating…’ / seems ok, but messages are not sent / not delivered, etc.)
  • At what time did it start? Is it still happening?
  • Is this happening all the time or sometimes?
  • Does this happen with all Telegram apps — or just one?
  • Does web.telegram.org work?
  • The problem happens on Wi-Fi, on mobile connection or in both cases?

Don't forget to include with your report:

  • User's phone number or #tq tag.
  • External IP address of the user for the device with the problem at the time of the problem.

It is possible that we'll need a Traceroute to our servers, here's how you get that. Wait for instructions from the server cultists to get the right IP to trace the route to — each case potentially requires a different one.

Last seen time is not displayed correctly

  • We use the user’s time zone. If he has manually entered a time different from the time zone, he will see the wrong time.
  • If an app force-quits, the user may remain online for 5-7 minutes after this.

If none of the two, pass to the volunteer group. We need to know:

  • The time zone and time set
  • Detailed description of the problem

NOTE: Support accounts are slightly different from ordinary user accounts. Due to some limitations, it is normal if you don't see the correct last seen time for users who are contacting Support.

User was blocked, but still sees last seen \ online status

The changes that come with blocking sometimes do not take effect immediately. Give it a few minutes, maybe half an hour — and the blocked user will stop seeing the status.

If a blocked user restarts the app or relogins, but can still see online status — pass to the volunteer group. This cannot happen under normal conditions.

TSF Manuals