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 bug report 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 regularly (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
Bugreport: 114798 Caused by: old Portage version Solution: update Portage and run
Attempts to install any and all packages result in "!!! No package digest file found:" errors
Caused by: portage-2.0.x does not have Manifest2 support Solution: manually update to at least portage-2.1
Receiving portage.db["/"]["porttree"].dbapi.auxdb[porttree_root][cat].clear() KeyError: 'app-dicts' while updating Portage cache
Bugreport: 100444 Caused by: old portage version Solution: update Portage and run
Any emerge operation results in "!!! 'str' object has no attribute 'insert'"
Bugreport: 63400 Caused by: ancient Portage version in combination with cascaded profiles Solution: a) manually update portage[ or b) use a flat profile according to bug 63400, update portage and update to a current (cascaded) profile
After emerge --sync, emerge "Calculating dependencies" takes an extremely long time. Similarly, after cvs update, "RepoMan scours the neighborhood" takes an extremely long time.
Bugreport: 124041 Caused by: invalid metadata cache in /var/cache/edb/dep Solution: run