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 encountering 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 or is in the “Hot and Trending” list). Then go right to step 4.
Trello cards are organized in lists that are pretty self-explanatory:
- The 'Hot & Trending' list has the most important cards
- 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. we can report any new occurrences in the comments (don't forget the footers) and try to find missing puzzle pieces (e.g. the issue happens only on specific devices / OS versions).
- 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.).
The very first card on each board contains a description for all labels and fields.
Fields
Cards can have a status field which describes what state the issue is in and whether or not it requires any actions on our TSF side. (E.g., “Needs info”, “Needs logs”, or “Confirm fix”). Feel free to update Happens in with the latest version you were able to reproduce the issue in. Other fields are mostly reserved for bug herders, including the Dev Priority field.
Labels
- Blue – A notable card. Being aware of what's inside may potentially help you recognize important issues and answer questions from users more easily.
- Yellow – This card is missing important information.
- Sky blue – This card mentions a workaround for the issue.
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:
- 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 on Trello.
- 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've added templates like this one to all boards. You can copy them and fill with info.
- 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.
- 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) we need 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?
- Make sure that your description has all the relevant keywords, so that it's easy to find the issue via search.
- When you add your first issue to Trello 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 description accordingly.
- Ask your teammates if you have any doubts.
Bug Groups
We're currently experimenting with TSF-wide bug groups for reporting and investigating issues in the apps. You can find a list in this card.
Custom Fields and Comments
- There are several custom fields. Fill in 'Happens in' with the hashtag of the version, e.g. #5_1_1_870. The rest of the custom fields are reserved for bug herders, please don't change them unless you're 200% sure you know what you're doing. You can read more about the fields in the first card on each board.
- Add a comment whenever a bug's state is changed.
- Discuss in the 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 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. Parachutes and pasties
- 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 of the link, after /c/ — e.g. vMFS4MZf).
- We use this ID to create a hashtag (e.g. #issue_vMFS4MZf) 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 delete old profile pictures in channels on the Android application. We reproduced it and are already working on a bug fix. Your issue #issue_lLyHjLRa has been recorded and we'll get back to you as soon as we have any news.
By the way, you can delete old profile pictures on the desktop client. Tell us if you want to learn more about it.
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 goals
- 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.
- 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, 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.