Diagnosing and Fixing Gentoo Portage Dependency Blockers, Slot Conflicts, and Unsatisfied Dependencies

Problem Statement

During an emerge @world or a targeted emerge operation Gentoo’s Portage may abort with one of the following fatal messages:

• !!! Multiple package instances within a single package slot have been pulled into the dependency graph – a slot conflict.
• !!! All ebuilds that could satisfy "…" have been masked – an unsatisfied dependency.
• !!! Error: The above package list contains packages which cannot be installed at the same time – a blocker or file collision.

These failures prevent the system from reaching a consistent state. The goal of this guide is to provide a concise diagnostic flow that isolates the root cause, applies the correct fix, and verifies the result without risking accidental removal of critical packages.

Recognizable Conditions and Quick Takeaway

The three messages above are the entry points. If you see any of them, stop the current emerge run, then follow the ordered checks below. The most common causes are USE‑flag conflicts, stale metadata, or overlay priority mis‑ordering. By addressing these first you usually resolve the problem in a single pass.

Root‑Cause Diagnostic Table

Cause	Typical Symptoms	What to Check
USE‑flag conflict pulling incompatible slots	Multiple versions of the same library in the graph, e.g. openssl-1.1-1.1.1k and openssl-3-3.0.0	Run emerge --pretend --verbose --tree @world and look for USE‑FLAG differences.
Stale repository or binary package index	Package cannot be found or masked even though it exists in the overlay.	Check /var/db/repos/gentoo and /var/db/pkg timestamps; run emerge --sync and eix-update.
Mixed stable/~arch KEYWORDS without package.accept_keywords	Package shows as masked but is present in the overlay.	Search /etc/portage/package.accept_keywords for the atom; verify ACCEPT_KEYWORDS in emerge --info.
Overlay priority mis‑ordering	A package from a lower‑priority overlay is pulled instead of the intended newer version.	Run eselect repository list and review the order.
Circular dependency introduced by a new ebuild revision	Emerging a package aborts with a long dependency loop trace.	Use emerge -pv --debug <atom> to view the circular‑dep chain.
Partial or failed previous install leaving orphaned packages	Emerging a package reports it is already installed but missing files.	Check /var/log/emerge.log for recent failures; run emerge --depclean --pretend.

Ordered Troubleshooting Steps

1. Refresh Metadata

   # emerge --sync
   # eix-update
   

   These commands update the local mirror list and the eix database. They ensure that Portage sees the latest ebuilds and that eix queries are accurate.

2. Visualise the Dependency Graph

   # emerge --pretend --verbose --tree @world
   

   Look for nodes marked with [blocks B] or [uninstall]. The tree view will also show which USE flags are causing multiple slots to be pulled.

3. Search Local Overrides

   # grep -R "package\.mask\|package\.unmask\|package\.accept_keywords" /etc/portage/
   

   Identify any package masks or keyword overrides that may be influencing the resolution. Pay special attention to /etc/portage/package.mask entries that mask entire slots.

4. Check Overlay Priority

   # eselect repository list
   

   Ensure that the overlay you intend to use (e.g., gentoo or custom-overlay) is listed before any fallback overlays that provide older versions.

5. Identify Circular Dependencies

   # emerge -pv --debug <problematic-package>
   

   Portage will print a Circular dependency trace. Note the atoms involved and whether they belong to @world or system packages.

6. Check for Orphaned Packages

   # emerge --depclean --pretend
   

   Review the list of packages that would be removed. If critical packages are listed, investigate why they are orphaned (e.g., manual installs not in @world).

7. Inspect Logs for Partial Installs

   # grep -i "error" /var/log/emerge.log | tail -n 50
   

   Look for entries that indicate a previous emerge aborted mid‑install, leaving a half‑built package.

Targeted Fixes Based on Findings

• USE‑Flag Conflict

  Edit /etc/portage/package.use to align flags. For example, to force openssl to use the 1.1 slot:

  # echo "dev-libs/openssl -threads" >> /etc/portage/package.use
  

  Re‑run emerge --pretend @world and verify the slot choice.

• Stale Metadata

  After emerge --sync, verify that /var/db/repos/gentoo/metadata/md5-cache has recent timestamps. If you use a binary host, run emaint sync -r gentoo to pull the latest binhost metadata.

• KEYWORDS Mismatch

  Add a minimal package.accept_keywords entry:

  # echo "=dev-libs/openssl-3.0.0 ~amd64" >> /etc/portage/package.accept_keywords
  

  Replace ~amd64 with your architecture. Afterward, run emerge --pretend @world to confirm acceptance.

• Overlay Priority

  Move the desired overlay to the top:

  # eselect repository move gentoo 1
  

  Replace gentoo with the overlay name and 1 with the target position. Test with emerge --pretend @world before committing.

• Circular Dependency

  Mask the offending revision until the maintainers release a fix:

  # echo "=dev-lang/python-3.12.0" >> /etc/portage/package.mask
  

  Use a full atom to avoid masking future security updates. After masking, run emerge --pretend @world to ensure the cycle is broken.

• Partial Install Cleanup

  Resume the interrupted install:

  # emerge --resume --skipfirst
  

  Alternatively, manually rebuild the package:

  # emerge -1 <atom>
  

Verification After Fixes

1. Zero Blockers

   # emerge --pretend @world
   

   Ensure the output contains no !!! error lines.

2. Check ACCEPT_KEYWORDS and USE

   # emerge --info | grep -E "ACCEPT_KEYWORDS|USE"
   

   Confirm that the environment matches the intended configuration.

3. Validate Dependency Graph Manually

   # equery depends dev-libs/openssl
   # equery depgraph dev-libs/openssl
   

   These commands from gentoolkit show the direct dependencies and the full dependency tree.

4. Check Package Database Integrity

   # emaint check world
   # emaint binhost --fix
   

   If you use binary packages, emaint binhost --fix will reconcile missing or mismatched packages.

Escalation Criteria

If the same blocker or conflict persists after applying the above fixes, consider escalating:

• Same blocker appears in three consecutive emerge attempts after a clean sync.
• Circular dependency involves system packages such as gcc, glibc, or systemd.
• File collision between two packages in the same slot that cannot be resolved by USE flags.
• A critical package (e.g., openssl, kernel) has been blocked for more than 30 days.
• Emerging --depclean proposes removal of more than 50 packages or any essential system component.

At this point, consult the Gentoo forums, bug trackers, or the relevant overlay maintainers. Provide the exact error messages, the output of emerge --pretend --verbose --tree @world, and the steps you already took.

Concrete Example: Slot Conflict Between OpenSSL 1.1 and 3

Suppose emerge @world aborts with:

!!! Multiple package instances within a single package slot have been pulled into the dependency graph: dev-libs/openssl[slot=1.1] dev-libs/openssl[slot=3]

Steps to resolve:

1. Check the tree

   # emerge --pretend --verbose --tree @world | grep -i openssl
   

   Identify which USE flags or packages are pulling each slot.

2. Align USE flags

   If openssl-3 requires threads but openssl-1.1 does not, add a package.use entry to force one slot:

   # echo "dev-libs/openssl -threads" >> /etc/portage/package.use
   

3. Mask the unwanted slot

   If you want to keep only the 1.1 slot:

   # echo "=dev-libs/openssl-1.1.1k" >> /etc/portage/package.mask
   

4. Verify

   # emerge --pretend @world
   

   Check that only one openssl slot appears.

Limitations and Cautions

• Never run emerge --depclean without --pretend. It can remove packages that are not explicitly in @world but are required by manually installed software.
• Auto‑unmasking writes to /etc/portage/package.accept_keywords/autounmask. Review each entry before committing to avoid pulling unstable packages.
• Masking a package with a generic atom (e.g., dev-libs/openssl) blocks all slots. Prefer version‑specific atoms to preserve future security updates.
• Overlay priority changes affect all packages from that overlay. After reordering, run emerge --pretend @world to confirm the desired versions are selected.
• Binary package hosts must match the client’s CHOST, CFLAGS, and USE flags. Mismatches can lead to silent source rebuilds or runtime failures.

Practical Check for Success

After applying fixes, the simplest test is:

# emerge --pretend @world

Zero blocker lines and a clean dependency graph indicate that the system can now resolve dependencies. A final sanity check is to run emerge --info and confirm that ACCEPT_KEYWORDS and USE match the intended configuration.

Conclusion

Dependency resolution failures in Gentoo are often a symptom of a misconfigured environment rather than a Portage bug. By following the ordered checks, applying targeted fixes, and verifying the result, you can restore a clean, reproducible system state. Use the escalation criteria to know when to seek community help, and always keep a backup of your /etc/portage directory before making bulk changes.