Portage/Help/Upgrade went wrong

This article is a stub. Please help out by expanding it - how to get started.

Sometimes, maybe an upgrade doesn't go well and you don't know what to do, despite following these excellent tips to keep your system in good shape: this page is for when that happens.

General tips:

1. Read your news items first.
2. Do share full output of all commands in support channels: don't cut off bits.
3. Never unmerge anything unless told to by a news item or a support channel as a last resort. Unmerging things is not a normal operation to have to do.
4. Check your world file for junk.
5. Use --keep-going=y on emerge invocations.
6. Start from the bottom upwards: the most fatal error is usually right down the bottom and causes noise above it. Resolving the bottommost issues usually sorts out the rest.

Long list of dependency conflicts

As above, start from the bottom and work upwards. Resolve one issue at a time then run emerge again.

Rough steps:

1. Check your world file (and follow the General tips listed above first).
2. Check /etc/portage for stale e.g. dev-qt/* (same for dev-haskell, games) entries (e.g. tightly versioned =dev-qt/foo-1.2.3 entries).
   1. Either no Qt should be in package.accept_keywords or all of Qt needs to be in there. Ditto Haskell.
   2. Make sure there's no too-specific entries like =games-misc/foo-1.2.3 which prevents it being upgraded.
3. If there's something obvious at the bottom (e.g. autounmask / package.use / package.accept_keywords changes suggested), act on it.
4. If there's nothing obvious at the bottom changes suggested, try more backtracking first: emerge -p -uvDU @world --backtrack=9999.
5. If, at this point, the entire thing looks like a huge wall with nothing easy, try: emerge --pretend -ev --backtrack=0. This often leads to emerge shaking out missing/outdated package.accept_keywords entries.
   1. For any lines that say "there are no ebuilds to satisfy ...", there are a few options:
      1. emerge --deselect ... for any packages which are no longer desired
      2. Fix the issue preventing them being installed (e.g. add them to package.accept_keywords)
   2. Run until there are no fixable issues
6. Try emerge -p -uvDU @world --backtrack=9999 again.
7. Failing that, try emerge -p -uvDU @world --ignore-built-slot-operator-deps=y. This should reveal some more output and allow further diagnosis of the problem. It's best not to use this option to do the upgrade (without pretend) unless truly needed. If it is used for the full upgrade, one must run emerge -a -uvDU @world afterwards.

(A common issue here is overly restrictive package.accept_keywords entries for e.g. games, Haskell, ...)