Gentoo Wiki


This article is still a Stub. You can help Gentoo-Wiki by expanding it.

This article is part of the FAQ series.
General Portage Wiki



This article seeks to be a comprehensive resource for troubleshooting emerge errors in portage. It mostly is a hub linking resources to the forum FAQ and website.

Note: The following steps, as outlined in this article, are sequential. Please move down the list from the top to figure out your problem

After it has matured, our portage developers could provide a link at the end of the emerge "ERROR ..." message for our fellow gentoo-ers to find quick solutions to their problems.

Note that while this article is aimed primarily at improving new user experience, being discussed in this forum thread, it also seeks to include useful steps for more experienced users. Concerns or Compliments? Please use the Discussion section.

Getting Started


Glance through the portage introduction, for basic understanding of the portage system, and also gentoolkit for useful tools like revdep-rebuild and equery

It will help later, if not now

emerge world Workaround

If the error throwing package is part of larger package set, or you are conducting a system update, the following emerge options allow you to continue on and then get back to it: emerge --resume --skipfirst You can use it to skip over more than one error by using emerge --resume --skipfirst as many times as it takes.

Warning: This command does NOT solve your emerge error(s), but allows for continuing an emerge. You will generally get further errors because earlier packages failed (particularly when installing new packages). , but definitely NEED to follow the rest of this guide to fix the error(s) afterward.

Portage problems

When emerge attempts of many different packages report the same error, you know that the problem lies with the portage (that is the emerge utility) itself. If this is not the case for you, continue reading the next section on FAQ_Troubleshooting_Emerge_Errors#Compiler Errors

Here are some errors with portage:

If portage cannot be fixed you can manually fix the portage utility

Compiler Errors


The FAQ forum has a browseable FAQ section to save you time searching through threads. A direct list, for the narrower scope of this GCC-emerge troubleshooting guide, has been provided below for convenience:

Read this if you want to expanding the forum FAQ: About this forum

Please do not post your workaround directly to the FAQ. If your problem could not explicitly resolved by the FAQ above, you may suggest a topic here.


To comply with generation 1 VM follow the Java upgrade guide. You may need to tweak your Java compiler selection or setting and

For setting up program structures like Samba, ALSA sound, etc, search both websites for context specific help.

Browsing the Forums

The chances are your error is probably already in discussion and maybe also resolved.

Look at the sticky threads under the category of your program:

TIP for thoroughly searching the Forums / Google

Pick out keywords peculiar to your error (such as name of the first error causing file, or library) along with significant other keywords there like "segfault", "linking", etc Search the forum, and then if need be use google with the same keywords.


Always choose the advanced search option in, and search all errors (i.e. shift-selecting every status).

Then if you need to narrow down your search, put in the keywords from the TIP section above.

More Self-help

Use stable version instead of ~(arch)

It is dangerous to globally enable the ~arch keyword in your /etc/make.conf

Disable USE flags

To disable USE flags you must use either /etc/make.conf or /etc/portage/package.use. While portage does allow you to specify USE flags on the command line, this method is to be avoided as the changes are not saved and will be reverted next time the package is merged. See the Gentoo Handbook for further details.

Version downgrade

Browse the portage tree for previous versions by visiting

To downgrade to a previous version, emerging the specific version is not enough - the package will simply be upgraded again in the future. You must use /etc/portage/package.mask to mask out unwanted versions, as detailed in the portage man page.

Getting community support

Posting for help on the forum



Instructions provided on that website already:

Retrieved from ""

Last modified: Fri, 05 Sep 2008 22:21:00 +0000 Hits: 3,355