<divclass="dev_page_bread_crumbs"><ulclass="breadcrumb clearfix"><li><ahref="/">Telegram Support Initiative</a></li><iclass="icon icon-breadcrumb-divider"></i><li><ahref="/manuals">Manuals</a></li><iclass="icon icon-breadcrumb-divider"></i><li><ahref="/manuals/bugs">Handling Bugs and Troubleshooting</a></li></ul></div>
<h1id="dev_page_title">Handling Bugs and Troubleshooting</h1>
<divid="dev_page_content"><!-- scroll_nav -->
<blockquote>
<p>This manual is intended for volunteers of the <ahref="/">TSF</a>, but anyone else is free to take a look as well.</p>
</blockquote>
<p>Every now and then users will report bugs in Telegram. The <ahref="#reporting-a-bug"><strong>step-by-step guide</strong></a> and <ahref="#troubleshooting-common-issues"><strong>troubleshooting tips</strong></a> on this page will help you deal with those reports in style and eventually help Telegram get rid of the bugs themselves.</p>
<p>See the <ahref="/manuals/bug_hunting"><strong>Bug Hunting Algorithm</strong></a> for tips on investigating new issues.</p>
<hr>
<h3><aclass="anchor-link"href="#reporting-a-bug"><iclass="anchor-icon"></i></a><aclass="anchor"name="reporting-a-bug"></a>Reporting a bug</h3>
<h4><aclass="anchor-link"href="#1-search-known-issues"><iclass="anchor-icon"></i></a><aclass="anchor"name="1-search-known-issues"></a>1. Search known issues</h4>
<p>We use <ahref="https://trello.com">Trello</a> boards to keep track of bugs (sorry, these boards are TSF-only, <ahref="/">here's how you join</a>), features and user suggestions, so your first stop when encountering a bug report is <strong>Trello search</strong>. 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.</p>
<p>If you have found the issue on Trello, leave a comment in the card with your user's <strong>#tq tag</strong> 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 <strong><ahref="#4-notify-the-user">step 4</a></strong>.</p>
<p>Trello cards are organized in lists that are pretty self-explanatory:</p>
<ul>
<li>The <strong>'Hot & Trending'</strong> list has the most important cards</li>
<li>Every card begins its journey in the <strong>'Unsorted'</strong> list.</li>
<li>Once the issue was reviewed by a <ahref="/manuals/bug_herding">bug herder</a> and reported to the developer, it moves to the <strong>'Reviewed & Reported'</strong> list. we can report any new occurrences in the comments (don't forget the <strong>footers</strong>) and try to find missing puzzle pieces (e.g. the issue happens only on specific devices / OS versions).</li>
<li>Finally, at some point, the card reaches <strong>'Fixed'</strong> status, is declared a <strong>'Feature'</strong> (this is how we want this to work), or <strong>'Not our bug'</strong> (platform restrictions, etc.).</li>
</ul>
<blockquote>
<p><em>The very first card on each board contains a description for all labels and fields.</em></p>
</blockquote>
<p><strong>Fields</strong><br>Cards can have a <strong>status</strong> 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 <strong>Happens in</strong> 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.</p>
<p><strong>Labels</strong></p>
<ul>
<li><strong>Blue</strong>– A <strong>notable</strong> card. Being aware of what's inside may potentially help you recognize important issues and answer questions from users more easily. </li>
</ul>
<ul>
<li><strong>Yellow</strong>– This card is <strong>missing important information.</strong></li>
<li><strong>Sky blue</strong>– This card mentions a <strong>workaround</strong> for the issue.</li>
</ul>
<hr>
<h4><aclass="anchor-link"href="#2-investigate-the-bug"><iclass="anchor-icon"></i></a><aclass="anchor"name="2-investigate-the-bug"></a>2. Investigate the bug</h4>
<blockquote>
<p><strong>IMPORTANT:</strong> Please see the <ahref="/manuals/bug_hunting">Bug Hunting Algorithm</a> after this manual for an in-depth look at investigating bugs.</p>
</blockquote>
<p>If you can't find anything useful on Trello:</p>
<ol>
<li>Check <strong>app version</strong>. Must be the <ahref="https://t.me/tgstable">latest available</a>.</li>
<li><strong>Reproduce the bug</strong>, if you have a relevant device on hand – using the <em>store version</em>. Mention if you can't reproduce it. Ask in the <ahref="#bug-groups">bug groups</a> if you don't have the device – don't forget to include all <strong>hashtags</strong> from the user's footer with your question and <strong>English summary</strong> (don't just forward the messages!).</li>
<li>Check the <ahref="#troubleshooting-common-issues">Troubleshooting Tips</a> below, there are some useful tips for identifying and reporting <strong>common issues</strong>.</li>
<li><strong>Find and ask the right questions</strong> 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 <ahref="/manuals/bug_hunting"><strong>Bug Hunting Algorithm</strong></a>.</li>
</ol>
<blockquote>
<p>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).</p>
<p>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.</p>
</blockquote>
<h4><aclass="anchor-link"href="#3-report-the-bug"><iclass="anchor-icon"></i></a><aclass="anchor"name="3-report-the-bug"></a>3. Report the bug</h4>
<p>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.</p>
<ol>
<li>Make sure you've really completed steps <strong><ahref="#1-search-known-issues">1</a></strong> and <strong><ahref="#2-investigate-the-bug">2</a></strong> of this guide.</li>
<li><strong>Important:</strong> Discuss the issue in the relevant <ahref="#bug-groups">bug group</a> — 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.</li>
<li>If you're sure this is necessary, add the issue to the board. We've added templates like <ahref="https://trello.com/c/3WxFPedg">this one</a> to all boards. You can copy them and fill with info.</li>
<li>Make sure your heading has all the relevant info. Fill in the rest of the details.</li>
<li>Always add the user's (and/or your own, if you reproduced the issue) footer with the <strong>system hashtags</strong>.</li>
<li>Add relevant <strong>screenshots</strong> or <strong>video</strong> to the issue. This is optional if the issue is clear enough without them.</li>
<li>If the problem involves <strong>particular</strong> 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). <em>Think: if you were a developer who just received your question, would you need to ask for more info instead of giving an answer?</em></li>
<li>Make sure that your description has all the <strong>relevant keywords</strong>, so that it's easy to find the issue via <strong>search</strong>.</li>
<li>When you add your first issue to Trello send the link to Daria — along with a picture of a beetle.</li>
<li>Think of the words you would use if you were looking for that issue — try them in the search box. Adjust the description accordingly.</li>
<li>Ask your teammates if you have any doubts.</li>
<p>We're currently experimenting with TSF-wide bug groups for reporting and investigating issues in the apps. You can find a list in <ahref="https://trello.com/c/iAH2kIDN">this card</a>.</p>
<h5><aclass="anchor-link"href="#custom-fields-and-comments"><iclass="anchor-icon"></i></a><aclass="anchor"name="custom-fields-and-comments"></a>Custom Fields and Comments</h5>
<ul>
<li>There are several custom fields. Fill in <strong>'Happens in'</strong> with the hashtag of the version, e.g. #5_1_1_870. The rest of the custom fields are reserved for <ahref="">bug herders</a>, 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.</li>
<li>Add a <strong>comment</strong> whenever a bug's state is changed.</li>
<li>Discuss in the groups, comments are for important <strong>updates</strong> to the bug only.</li>
<li>Make sure the bug's description covers all the important info that emerged in the comments.</li>
</ul>
<h4><aclass="anchor-link"href="#4-notify-the-user"><iclass="anchor-icon"></i></a><aclass="anchor"name="4-notify-the-user"></a>4. Notify the user</h4>
<p>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</p>
<ul>
<li>Always include an <strong>issue ID hashtag</strong> in your reply in this situation.</li>
<li>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. <em>vMFS4MZf</em>).</li>
<li>We use this ID to create a hashtag (e.g. <strong>#issue_vMFS4MZf</strong>) and include it in our reply to the user with that problem. Like this, for example:</li>
</ul>
<blockquote>
<p>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.</p>
<p>By the way, you can delete old profile pictures on the desktop client. Tell us if you want to learn more about it.</p>
</blockquote>
<p>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.</p>
<h4><aclass="anchor-link"href="#5-stick-to-our-goals"><iclass="anchor-icon"></i></a><aclass="anchor"name="5-stick-to-our-goals"></a>5. Stick to our goals</h4>
<ol>
<li>Our final goal in case of any bug is to create a report in Trello that would get the status <strong>confirmed by a developer</strong> or <strong>feature</strong>.</li>
<li>If no report was created or no existing relevant report found — we did <strong>nothing</strong>, regardless of how much time we spent talking to the user or TSF members in our groups and diagnosing the issue.</li>
</ol>
<p>In order to achieve this goal with a clear conscience, we need to respect our users'<strong>time</strong> and <strong>effort</strong> — a little more on this below:</p>
<hr>
<h4><aclass="anchor-link"href="#a-note-on-users"><iclass="anchor-icon"></i></a><aclass="anchor"name="a-note-on-users"></a>A note on users</h4>
<p>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 <strong>asset</strong> when it comes to bugs. They can help us identify bugs and improve usability.</p>
<p>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 <strong>minimum actions — maximum effect</strong>. Rabid bunnies alert</p>
<p>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.</p>
<hr>
<p>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.</p>
<hr>
<h3><aclass="anchor-link"href="#troubleshooting-common-issues"><iclass="anchor-icon"></i></a><aclass="anchor"name="troubleshooting-common-issues"></a>Troubleshooting common issues</h3>
<blockquote>
<p>This advanced troubleshooting guide is intended for volunteers of the <ahref="/">Telegram Support Force</a>.<br>Everyone else is also welcome to take a look. Help friends and loved ones — or troubleshoot yourself!</p>
<p><strong>iOS:</strong> Device must run iOS 8 or higher.</p>
<p><strong>Android: </strong><br>- If SDK >= 16 —> Android version must be 4.1<br>- Ask whether other applications install ok<br>- If nothing helps we need to know the Android version and device model</p>
<h4><aclass="anchor-link"href="#messages-not-getting-delivered"><iclass="anchor-icon"></i></a><aclass="anchor"name="messages-not-getting-delivered"></a>Messages not getting delivered</h4>
<p>The following cases cover pretty much all the complaints:</p>
<ul>
<li>The user may be confused by the check system. In Telegram: 1 check = message sent, 2 checks = message <strong>read</strong> (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.</li>
<li>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.</li>
<li>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 <ahref="#notification-problems">notification problems</a>.</li>
<li>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.</li>
<li>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.</li>
</ul>
<p>In case it's none of these five (but it <em>must</em> be one of these five, really), this is one of the worst things that can ever happen in Telegram. We need to know:</p>
<ul>
<li>Phone numbers for <em>all</em> participating users</li>
<li>Devices and app types for <em>all</em> users</li>
<li>Make sure notifications are on in Telegram AND in phone settings (Settings > Notifications), check app version.</li>
<li>Make sure notifications weren’t disabled for a specific chat or group.</li>
<li>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.</li>
</ul>
<p>What we need to know if nothing helps:</p>
<ul>
<li>User’s <strong>footer tag</strong>.</li>
<li>Type of problem (notifications: a. never come, b. come only sometimes)</li>
<li><strong>Logs</strong> that capture the problem and <strong>time</strong> of when the message was received.</li>
</ul>
<p><strong>Android:</strong></p>
<ul>
<li>Make sure the latest app version is installed.</li>
<li>Go to <em>Telegram Settings > Notifications and Sounds</em>, make sure that notifications are ON and Importance is set to “High” or greater.</li>
<li>Check notification priority for Telegram in Android settings, it can be called Importance or Behaviour depending on the device.</li>
<li>Make sure notifications weren’t disabled for a specific chat.</li>
<li>Make sure that <ahref="https://play.google.com/store/apps/details?id=com.google.android.gms">Google Play Services</a> are installed on the device.</li>
</ul>
<blockquote>
<p>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. </p>
<p>Huawei: Phone Manager App > Protected apps > Add Telegram to the list.<br>Xiaomi: Services > Security > Permissions > Autostart, find Telegram and enable autostart.<br>Samsung: Settings > Device Maintenance > Battery > Unmonitored Apps, then add Telegram to that list.</p>
</blockquote>
<p>In case you went through all the steps to no avail, we need to know:</p>
<ul>
<li>User’s phone number (username) or footer tag so we can find the user again to followup.</li>
<li>Type of problem (notifications: a. never come, b. come only sometimes)</li>
<li><strong>System</strong> and <strong>app logs</strong> that capture the problem and <strong>time</strong> of when the message was received.</li>
<p>User doesn’t see his contacts in Telegram. Or sees numbers instead of names in Messages list.</p>
<blockquote>
<p><strong>Important:</strong> Naturally, one of the easiest ways to solve this would be to save the number in international format. <strong>Do not advise this before other methods.</strong> Our systems <strong>must</strong> 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.</p>
</blockquote>
<p><strong>iOS:</strong></p>
<ul>
<li>Temporarily change the name of the missing contact in Phone Contacts (not in Telegram) — add a few symbols, then change back again</li>
<li>If that doesn’t help, relogin</li>
</ul>
<p>Things we need to know if nothing helps:</p>
<ul>
<li>User’s phone number</li>
<li>Phone number(s) of the contact(s)</li>
<li>How exactly these numbers are stored in users phone book (international format or anything else?)</li>
<li>Devices and app versions for all users</li>
</ul>
<p><strong>Android:</strong></p>
<ul>
<li>Relaunch the app (not relogin! that won’t help) — swipe the app off the currently-running-apps list</li>
<li>Temporarily change the name of the contact in phone contacts (add a few symbols, then change back again)</li>
</ul>
<p>Things we need to know if nothing helps:</p>
<ul>
<li>User’s phone number</li>
<li>Phone number(s) of the contact(s)</li>
<li>How exactly these numbers are stored in users phone book (international format or anything else?)</li>
<p>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).</p>
<p>What we need to know:</p>
<ul>
<li>Problem occurs in one app only, or in all apps (e.g. in iOS and TDesktop on the same Wi-Fi).</li>
<li>Problem occurs when sending or receiving (uploading / downloading)? Or both?</li>
<li>What Internet connection is being used? If Wi-Fi, advise user to try LTE and vice versa and see what changes.</li>
<li>Recipient and sender's footer tags (or username/number).</li>
<li>Time of problem (better include the timezone too).</li>
<li>In case of a photo/video, ask the user to forward it to us. <strong>Not</strong> upload it again, just forward the original message with the attachment.</li>
<p>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:</p>
<ul>
<li>Do other (non-Telegram) apps work OK?</li>
<li>What exactly is happening? (always 'connecting…' / always 'updating…' / seems ok, but messages are not sent / not delivered, etc.)</li>
<li>At what time did it start? Is it still happening?</li>
<li>Is this happening all the time or sometimes?</li>
<li>Does this happen with all Telegram apps — or just one?</li>
<li>Does web.telegram.org work?</li>
<li>The problem happens on Wi-Fi, on mobile connection or in both cases?</li>
</ul>
<p>Don't forget to include with your report:</p>
<ul>
<li>User's footer tag.</li>
<li>Results of <ahref="https://t.me/connectivity_test">@connectivity_test</a>. Which GIFs are downloaded slowly or not downloaded?</li>
<p>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.</p>
<h4><aclass="anchor-link"href="#last-seen-time-is-not-displayed-correctly"><iclass="anchor-icon"></i></a><aclass="anchor"name="last-seen-time-is-not-displayed-correctly"></a>Last seen time is not displayed correctly</h4>
<ul>
<li>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.</li>
<li>If an app force-quits, the user may remain <em>online</em> for 5-7 minutes after this.</li>
</ul>
<p>If none of the two, pass to the volunteer group. We need to know:</p>
<ul>
<li>The time zone and time set</li>
<li>Detailed description of the problem</li>
</ul>
<blockquote>
<p><strong>NOTE:</strong> Support accounts are slightly different from ordinary user accounts. Due to some limitations, it is <strong>normal</strong> if you don't see the correct last seen time for users who are contacting Support.</p>
</blockquote>
<h4><aclass="anchor-link"href="#user-was-blocked-but-still-sees-last-seen-online-status"><iclass="anchor-icon"></i></a><aclass="anchor"name="user-was-blocked-but-still-sees-last-seen-online-status"></a>User was blocked, but still sees last seen / online status</h4>
<p>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.</p>
<p>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.</p>
<p>Log in here to access your TSF stats. Please enter your <b>phone number</b> in the <atarget="_blank"rel="noopener"href="https://telegram.org/faq#login-and-sms">international format</a> and we will send a confirmation message to your account via Telegram.</p>
