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
Telegram has a public Bug and Suggestion Platform for tracking bugs, features, and user suggestions, so the first step when handling a bug report is to search there. Most likely, we already know about the issue — sometimes it is not a bug at all.
If you have found the card that describes the issue and it has been reported to the devs, you can go right to step 4. If it hasn't been reported to the devs yet, please discuss the issue in the relevant bug group, including the card link in your message.
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 the Bug and Suggestion Platform:
- Check app version. Must be the latest available.
- Reproduce the bug, if you have a relevant device on hand – using the store version. Mention if you can't reproduce it. Ask in the bug groups if you don't have the device – don't forget to include all hashtags from the user's footer with your question and English summary (don't just forward the messages!).
- Check the Troubleshooting Tips below, there are some useful tips for identifying and reporting common issues.
- Find and ask the right questions that allow 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.
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.
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.
- Make sure you've really completed steps 1 and 2 of this guide.
- Important: Discuss the issue in the relevant bug 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.
- If you're sure this is necessary, add the issue to the board. We have a formatting guide for new cards, please use the formatting suggested there.
- Make sure your heading has all the relevant info. Fill in the rest of the details.
- Always add the user's (and/or your own, if you reproduced the issue) footer with the system hashtags to the internal block.
- Add relevant screenshots or video to the issue. This is optional if the issue is clear enough without them.
- If the problem involves particular items (account, photo, group, message, etc), use the internal block to add the coordinates required to locate that particular item (tq/footer, phone number, username, link, Telegram Web address bar string, forwarded copy). Think: if you were a developer who just received your question, would you need to ask for more info instead of giving an answer?
- When you add your first issue to Bug Tracker send the link to Daria — along with a picture of a beetle.
- Think of the words you would use if you were looking for that issue — try them in the search box. Adjust the card accordingly.
- Ask your teammates if you have any doubts.
Bug Groups
We're currently using TSF-wide bug groups for reporting and investigating issues in the apps. You can find a list in this card.
4. Notify the user
Once we're done, we need to get back to the user and tell them 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. The user can upvote the relevant card on the Bugs and Suggestions platform and subscribe to it to receive notifications when it’s fixed or whenever there’s another status update. Parachutes and pasties
5. Stick to our goals
- Our final goal in case of any bug is to create a report that would get the status confirmed by a developer or feature.
- 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 or TSF members in our groups and diagnosing the issue.
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. They can help us identify bugs and improve usability.
So when somebody comes with a problem, we are not looking for a way to make them 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 them 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 8 or higher.
Android:
- If SDK >= 16 —> Android version must be 4.1
- 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 they are in fact waiting for it to be read.
- The user may be blocked. When a user is blocked, they will not be notified in any way. Their 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
iOS:
- Make sure notifications are on in Telegram AND in phone settings (Settings > Notifications), check app version.
- Make sure notifications weren’t disabled for a specific chat or group.
- Shut down Telegram (go to home screen, swipe up or double tap home button, swipe upwards on Telegram), then go to Phone Settings and disable alerts. Relaunch Telegram, go to Phone Settings, enable alerts.
What we need to know if nothing helps:
- User’s footer tag.
- Type of problem (notifications: a. never come, b. come only sometimes)
- Logs that capture the problem and time of when the message was received.
Android:
- Make sure the latest app version is installed.
- Go to Telegram Settings > Notifications and Sounds, make sure that notifications are ON and Importance is set to “High” or greater.
- Check notification priority for Telegram in Android settings, it can be called Importance or Behaviour depending on the device.
- Make sure notifications weren’t disabled for a specific chat.
- Make sure that Google Play Services are installed on the device.
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. Samsung devices also may require some manipulations.
Huawei: Phone Manager App > Protected apps > Add Telegram to the list.
Xiaomi: Services > Security > Permissions > Autostart, find Telegram and enable autostart.
Samsung: Settings > Device Maintenance > Battery > Unmonitored Apps, then add Telegram to that list.
In case you went through all the steps to no avail, we need to know:
- User’s phone number (username) or footer tag so we can find the user again to followup.
- Type of problem (notifications: a. never come, b. come only sometimes)
- System and app logs that capture the problem and time of when the message was received.
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.
iOS:
- 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
Android:
- 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. in iOS and TDesktop on the same Wi-Fi).
- Problem occurs when sending or receiving (uploading / downloading)? Or both?
- What Internet connection is being used? If Wi-Fi, advise user to try LTE and vice versa and see what changes.
- Recipient and sender's footer tags (or username/number).
- 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 footer tag.
- Results of @connectivity_test. Which GIFs are downloaded slowly or not downloaded?
It is possible that we'll need a Traceroute to our servers, then please 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.