The death of Moshiach ben Yosef is a very interesting topic, and needs explanation and discussion.
The only time that Moshiach ben Yosef is mentioned in the Gemara is in Succah daf 52A. There the Gemara brings the passuk in Zechariah (12) which speaks of a great eulogy which will take place in the times of Moshiach. There is an argument as to who is the subject of the eulogy. One opinion is that they are mourning the death of Moshiach ben Yosef, and the other opines that they are mourning the death of the yetzer hara (evil inclination). The Gemara then says that after Moshiach ben Dovid sees that Moshiach ben Yosef has been killed, he beseeches Hashem to spare him from death. To this request, Hashem responds with an assurance that he will indeed be spared.
A number of issues beg for an explanation. The most obvious question is, Why must Moshiach ben Yosef die? At which point is he to die? Has he completed any of his mission yet?
So let us start off with some information, and I will again mention that most of what I am about to write comes from shiurim from Rav Shimon Kessin.
Moshiach ben Yosef's jobs are many, and they include bringing the entire Jewish people back to Israel, infusing them with a newfound spirituality, and revealing the secrets of the Torah, among other things. Another important task that he is to accomplish is the complete destruction of Edom, as the passuk says in Ovadiah, והיה בית יעקב אש ובית יוסף להבה ובית עשו לקש ודלקו בהם ואכלום - the house of Yakov will be fire, and the house of Yosef a flame, and the house of Esav will be like straw, and he shall light them and consume them.
This final purpose follows all the other ones, and is the reason why he leads the Jewish people in the war of Gog and Magog. Although many people mistakenly think otherwise, this great war is actually after Moshiach ben Yosef has done most of his job, and actually segways us into the period of Moshiach ben Dovid.
If we can imagine the scene for a moment, we have Moshiach ben Yosef who has led the entire Jewish people to a genuine spiritual rennaisance, returning the entire nation back to their rightful homeland, to Israel. He represents the promise of a new age for humanity, one of peace, love and harmony. And yet, he is challenged by a force known as Gog and Magog. This force is actually composed of a few different components, but is mainly led by Amalek, the arch-enemy of the Jewish people (which reared its ugly head in World War II in the form of the Nazis of Germany), as well as the Erev Rav - that section of the Jewish people who attempts to remove the Jewish people's relationship with Hashem. They combine forces with many other nations of the world (see Yechezkel 38-39) to try to prevent the triumph of Moshiach ben Yosef and his mission to remove evil from the hearts of mankind. This true axis of evil, however, would rather die than allow mankind to be beholden to the Higher Power that created them.
Just as Moshiach ben Yosef is about to destroy the last vestiges of evil, the leader of the Erev Rav, named Armilus, is somehow able to kill him. Can we imagine the sheer horror of the Jewish people, so close to redemption, watching its progress wrenchingly arrested? Yet this is the scenario that the Gemara describes. The question again is, Why?
To begin to understand this, let us ask another interesting question. The gemara we quoted earlier stated that when Moshiach ben Dovid (who is also involved to some extent in the war) sees that Moshiach ben Yosef has been killed, he pleads with Hashem to spare his own life. Why does he fear for his life, just because ben Yosef has been killed? This question is asked by one of the commentaries on the gemara, the Einei Shmuel.
He answers that the root cause of Moshiach ben Yosef's death goes back to a mistake that Dovid Hamelech himself made. Dovid accepted loshon hara (slander) that was told to him about Mefiboshes, instead of giving him the benefit of the doubt. The result of this was that the Dovid's kingdom - the Jewish nation - would be split in two after Shlomo's reign. This meant that the kingdom of Yehuda would come under Rechovom ben Shlomo, and the new kingdom of Yisrael would come under the kingship of Yerovom ben Nevat. As always, Hashem gave the opportunity for a negative situation to still have the potential for salvation, and thus, Rechovom had the potential to be Moshiach ben Dovid, and Yerovom, in fact, was a hairsbreadth away from being Moshiach ben Yosef. Yerovom was an incredible Torah scholar who was well-versed in the deepest secrets of the Torah (as is MBY's role), however, he committed a grievous sin at a point after the yechida (the highest level of the soul that it is MBY's job to bring down) had already entered him! It actually flew out of him just before his horrible sin, which involved causing his entire kingdom to bow down to Golden calves. But the blemish he caused would have to be rectified by the final Moshiach ben Yosef.
It is for this reason that Moshiach ben Dovid prays for his life - because it was the sin of Dovid that had opened the possibility for Yerovom's great sin that is to be rectified by the death of Moshiach ben Yosef!
Rav Kessin points out that although Moshiach ben Yosef is killed, at a certain point, Moshiach ben Dovid actually brings him back to life in order to complete the rectification they must do together, and this actually begins the period of the revival of the dead.
Now, what is interesting is something I intentionally mentioned at the very beginning of this whole piece, and that is that the gemara actually has two opinions as to who is being eulogized in the verse. The explanation we have given until now is based on the opinion that Moshiach ben Yosef is the one who dies. There is another opinion, however, that it is the yetzer hara (evil inclination) that is being 'eulogized.' According to this opinion, Moshiach ben Yosef does not die, but rather, actually completes his task of destroying the forces of evil, and thus removes the evil inclination from the world (to a certain extent).
According to the Gra and others, indeed, the decree of death for Moshiach ben Yosef has been rescinded (עוד יוסף חי), and thus the second opinion of the gemara is the one that will actually play out in reality. This is due to the length of the exile the Jewish people has endured, which has actually completely atoned for the sin of Yerovom ben Nevat, and therefore removed the need for Moshiach ben Yosef's death.