This document deals only with major problems preventing normal operation that have affected a significant number of users in the past (or problem we expect to affect a significant number of users). If you have a problem and don't find it listed here please check if the problem is listed at bugzilla (please also search for closed/resolved bugs), and if not please file a bugreport there, even if you found a solution or workaround somewhere else.
Often the solution to a portage related problem is to simply update portage first. We recommended to do that regulary (every three or four months), as over time the portage tree will make use of features introduced by new portage releases, and that will often break old versions. We generally make sure that the tree is compatible with portage versions released in the past six months, so if you don't have version released in that timeframe it is possible that you won't be able to use the tree anymore.
The recommended way to upgrade portage is a simple emerge portage without any options, especially without the --update option as it causes some unwanted behavior for single package updates.
Receiving "!!! Cannot resolve a virtual package name to an ebuild." while updating portage cache
Attempts to install any and all packages result in "!!! No package digest file found:" errors
Receiving
portage.db["/"]["porttree"].dbapi.auxdb[porttree_root][cat].clear()
KeyError: 'app-dicts'
while updating portage cache
Any emerge operation results in "!!! 'str' object has no attribute 'insert'"
After emerge --sync, emerge "Calculating dependencies" takes an extremely long time. Similarly, after cvs update, "RepoMan scours the neighborhood" takes an extremely long time.
The contents of this document are licensed under the Creative Commons - Attribution / Share Alike license.