While I was performing the sunnah prayer of tahiyyatul masjid, then I heard the iqamah for the obligatory prayer. What should I do? Should I complete my sunnah prayer or invalidate it to follow the congregational prayer?
Alhamdulillah, praise and thanks to Allah for the countless blessings He has blessed us all with. Blessings and salutations to the Prophet Muhammad PBUH, his wives, his family, companions and all those that follow his teachings to the day of judgement.
To answer this question, we would like to first include a few example of situations where the above problem would arise.
While performing the sunnah prayer, the iqamah is heard. What should be done?
- If we enter the mosque when the iqamah has started (for obligatory prayer), then it is makruh (undesirable) for us to perform any sunnah prayers and we should prepare ourselves for the congregational obligatory prayer. This is in accordance with a hadith from Abu Hurairah RA, where the Prophet PBUH said:
إِذَا أُقِيمَتِ الصَّلاَةُ فَلاَ صَلاَةَ إِلاَّ الْمَكْتُوبَةُ
“When the Iqamah for prayer is said, there is no prayer except the prescribed prayer.”
Sahih Muslim (710)
Al-Imam al-Nawawi Rahimahullah said: “It is makruh (undesirable) to perform sunnah prayers for Subuh, Zuhur and other sunnah prayers (ratib) after the iqamah is said, whether or not he is sure he has enough time to join the congregational prayer with the imam.” 
- While we are performing our sunnah prayer, then the iqamah is said, then it is sunnah for us to complete our sunnah prayer, if there is enough time for us to join the congregational prayer before the imam gives his salam. . Allah SWT states:
يَٰٓأَيُّهَا ٱلَّذِينَ ءَامَنُوٓاْ أَطِيعُواْ ٱللَّهَ وَأَطِيعُواْ ٱلرَّسُولَ وَلَا تُبۡطِلُوٓاْ أَعۡمَٰلَكُمۡ
“O you who have believed, obey Allah and obey the Messenger and do not invalidate your deeds.”
Surah Muhammad (33)
However, it is encouraged for us to simplify our sunnah prayer (while making sure to fulfil the prerequisites of prayer) and quickly join the congregational prayer and it is prioritized to join the prayer during the takbiratul ihram with the imam.
- If there is a possibility that we would miss the congregational prayer, then it is sunnah for us to end our prayer and gives salam. As for Friday prayer, if there is a possibility that there is not enough time to join the Friday prayer, then it is obligatory to end the sunnah prayer.
- If while the sunnah prayer is performed, then the iqamah for obligatory prayer is said and he is certain that if he completes his sunnah prayer, then he would miss the congregational prayer, but he is also certain that there will be other people arriving later to perform congregational prayer with him, then it is prioritized for him to complete his sunnah prayer.
If he is performing his obligatory prayer alone, then other people arrive to perform a congregational prayer, what should he do?
- If there is a congregational obligatory prayer when he is performing his Subuh or Maghrib obligatory prayer alone or prayers that are of 4 rakaat (Zuhur and Asar), if he has completed his first two rakaat and is in his third rakaat, then he has to complete his prayer and then join the congregational obligatory prayer that was performed at the time. 
- If he is still in his first or second rakaat (haven’t reach the third rakaat), it is sunnah for him to change his intention of his prayer to sunnah prayer, simplified it to two rakaat and join the congregational obligatory prayer that was performed at the time. 
- If he does not want to end his obligatory prayer, nor does he want to change his intention of prayer to sunnah prayer and remain praying alone, then the ruling for it is makruh (undesirable). A prayer is valid even if he starts praying alone and ended up congregationally.
As an example, Amer is praying Zuhur alone in a mosque and was in his third rakaat (while he was reciting al-Fatihah), then came a group of people performing congregational prayer together. The congregational prayer begins, and Amer joins the congregational prayer together with them. When the congregation reached the first tahiyyat, Amer would have reached the final tahiyyat for his prayer, for he has already prayed two of first rakaat alone, then he joined the congregation. In this situation, Amer has two choices; he can either choose to mufaraqah (separate from the congregation) and gives salam to end his prayer or Amer can wait in his final tahiyyat position and give his salam together with the imam.
As discussed above, if someone is performing his sunnah qabliyyah prayer and then he heard the iqamah, then he can end his sunnah prayer if he feared that he would miss his Friday prayer. However, if he is certain that he has time to complete his prayer without missing the congregational prayer, which means that he has time to join the congregation, then it is prioritized for him to complete his sunnah prayer first. May Allah SWT make us be among the successful in taking care of our prayers and fulfils its rights.