docs/guide/troubleshooting.btft

[table class="topnav"]
[tr]
[td class="logotab"]mp[e]
[td][see name="index"]index[e][e]
[td][see name="guide/index"]guide[e][e]
[td][see name="reference/index"]reference[e][e]
[e]
[e]
 
[h1]troubleshooting[e]
 
what mp's own error messages mean, and what to actually do about each one.
 
[h2]"X conflicts with installed package Y, use --force to override"[e]
 
X's own pkg_conflicts (or an already-installed package's pkg_conflicts naming X) declared a hard conflict. this is usually correct and should be respected -- two libcs, two inherently incompatible builds of the same thing. "mp install --force X" overrides it for one invocation, if you're certain. if X is a %tag dependency, mp already tried every OTHER provider first and backtracked automatically -- seeing this message at all means every provider conflicted.
 
[h2]"X conflicts with Y on installed files, use --force to override"[e]
 
a real file-path overlap: X's install would overwrite a file Y already owns, not a declared pkg_conflicts relationship. --force overrides it unconditionally (skips the check entirely, for every package), but consider first whether X and Y genuinely should coexist (maybe one needs a SLOT) or whether one of them is simply misconfigured (a wrong install prefix, say).
 
two narrower, real resolutions short of --force: CONFLICT_PRIORITY ([see name="reference/mp-conf-example"]mp.conf.example[e]'s own documentation has the full grammar) lets one side win automatically and persistently, e.g. "busybox has priority over gnu-patch's own /usr/bin/patch" -- checked BOTH at a fast pre-flight pass (before a conflicting package's own rebuild even starts, using its last-known manifest, so a known, priority-decided rejection doesn't waste a full build) and at the real, authoritative post-install check. with neither side declaring a priority, a real terminal gets asked once, interactively -- "X wants to overwrite N file(s) Y currently owns -- let X win? [y/N]" -- a plain "y" there applies only to that one install, never persisted automatically (write CONFLICT_PRIORITY by hand for that). either way X wins, Y's own manifest is updated to stop claiming exactly the paths X took over, so Y's own tracking doesn't drift from reality afterward.
 
if X and Y look completely unrelated (nothing about their own files should ever plausibly overlap) and X has a long build: phase, suspect a timing race instead of a real overlap: this check works by snapshotting X's own install prefix immediately before and after X's install: phase specifically (narrowed to just that phase, not X's whole fetch-through-install run, precisely to keep this window as short as possible) and diffing against every OTHER package's own manifest. if Y happens to be reinstalled by a completely separate, concurrent "mp" invocation while THAT diff window is open, Y's own legitimate change lands inside X's snapshot and gets misattributed to X -- reproduced for real once (a long build-tools/cmake build blamed for a change coreutils/busybox's own concurrent reinstall made to its own bin/busybox, before this narrowing existed).
 
mp DOES now hold a per-package lock (canon_lock, reentrant within one process) across a package's own whole reinstall-lifecycle and install: snapshot window -- two concurrent "mp install"/"mp reinstall" runs targeting the exact SAME package can no longer race each other at all (confirmed directly: before this lock existed, two concurrent reinstalls of one already-installed package could each fail outright racing on its own stage directory, "can't open 'remove.sh'"/"can't open 'install.sh'"; now the second simply waits its turn). what remains open is the CROSS-package case above (X and Y are two DIFFERENT packages) and any ambient path a running service mutates on its own (an active log file some other package's install: happened to pre-create, say) -- narrower than before, but not eliminated, since serializing every install against every OTHER install would give up the real, intentional cross-package parallelism db_lock/canon_lock both go out of their way to preserve. two remedies for what's left: don't run concurrent "mp install"/"mp reinstall" operations for DIFFERENT packages against the same live prefix at the same time if you can help it, and for a specific, confirmed-legitimate ambient path that's expected to be mutated by something other than its own owning package's install (see resolve.pm's own %shared_ambient, currently share/info/dir and dev/null, both added after a real incident each) -- extend that list rather than reaching for --force as a standing workaround.
 
[h2]"dependency cycle at X"[e]
 
X depends (directly or through a chain) on itself. a real cycle in pkg_deps is a port authoring bug -- fix the port. pkg_deps_soft exists precisely to let a genuinely optional, potentially-cyclic edge (see ports/coreutils, ports/shells, ports/libcs' own bootstrap-triangle deps) skip silently instead of failing here; if the cycle you're hitting is conceptually optional, that's the tool to use, not --no-deps (which skips ALL dependency resolution for the whole install, a much blunter instrument).
 
[h2]"X cannot be (re)installed: held by config (HOLD=yes)"[e]
 
X is held. "mp unhold X" lifts a plain hold; if it's config you hand-wrote rather than something "mp hold" set, edit it out directly. HOLD_VERSION mismatches report the exact expected version in the message -- reinstall at that version, or edit/remove the HOLD_VERSION= line.
 
[h2]"X cannot be installed: masked by config" / "does not satisfy ACCEPT_KEYWORDS"[e]
 
masked (MASK=yes) or keyword-gated (pkg_keywords doesn't list your ACCEPT_KEYWORDS arch, and you have ACCEPT_KEYWORDS set at all). --unmask on the command line overrides either, for one invocation, without touching the persisted setting. "mp unmask X" instead lifts a persistent mask -- the two are independent, and a persistent mask still needs --unmask on any install meant to override it.
 
[h2]"no port provides tag %X" / "no provider of %X could be installed without conflicting"[e]
 
the first means literally nothing in any configured repo declares pkg_tags containing X -- check TARGET_X=/TAG_X= isn't pinning a typo'd or nonexistent port, and that the repo you expect to provide it is actually configured (see reference/multi-repo.html) and reachable. the second means providers exist, but every one of them conflicts with something already installed -- resolve the underlying conflict first (see above), or explicitly install your preferred provider by name so the pick isn't left to pkg_pref.
 
[h2]"warn: sandbox unshare failed" / "sandbox mount isolation failed"[e]
 
the Linux sandbox (fresh network + mount namespace per phase) couldn't set up -- often because the build itself is already running inside some other container/sandbox that won't allow nested namespaces. this is defense in depth, not a hard boundary: mp warns and continues unsandboxed rather than failing the build. SANDBOX="no" in mpx.conf turns it off deliberately and quietly, if the warning is expected and unwanted noise.
 
[h2]"X already staged, run: mp.clean X"[e]
 
a previous install of X didn't finish (was interrupted, or crashed) and left its staging workspace behind. "mp clean X" removes it; the next install starts fresh.
 
[h2]"X cannot be removed: still linked against by: Y (--force to override)"[e]
 
the revdep safety net (reference/slots.html): a slotted package something else's build was actually wired against. removing it anyway (--force) will break Y at runtime unless Y is also being removed/rebuilt in the same operation. "mp revdep X" shows the same list without attempting a remove, to check first.
 
[h2]"Read-only file system" inside a build (mkfifo, tempdir, or similar)[e]
 
a build tool tried to create a file under /tmp and the sandbox (SANDBOX="yes", the default) said no -- root is read-only except the port's own stage dir and the install prefix, and /tmp is neither. two real, confirmed shapes of this: GNU Make 4.4+'s default FIFO-style jobserver needs to mkfifo(1) under $TMPDIR (unset -> /tmp) the moment ANY nested "make -f -"-style invocation tries to join a jobserver (inherited via mpx's own MAKEFLAGS="-jN", set unconditionally regardless of whether the command asked for -j itself) -- hits gcc's own bundled gettext prerequisite's dependency-tracking bootstrap as "config.status: error: Something went wrong bootstrapping makefile fragments for automatic dependency tracking", a genuinely misleading error text for what's really a sandbox/tmpdir problem. autoconf's own Autom4te::General creates a real tempdir via Perl's File::Temp, same default, same failure, hit running autoreconf directly (classes/autotools.mp and bootstrap-make.mp both export TMPDIR for exactly this). fix: "export TMPDIR=\"$PWD\"" near the top of the affected phase -- points every tempfile/jobserver-FIFO call at the port's own stage dir instead, which the sandbox does leave writable. reproduce/confirm directly with "mpx runsh <stagedir> <script>" running "mkfifo <stagedir>/x" (works) vs "mkfifo /tmp/x" (fails) from inside the sandbox, if a new failure looks like this shape but isn't one of the two above.
 
[h2]"mp dryrun" vs "mp install --dry-run"[e]
 
dryrun is its own top-level command ("mp dryrun X", or "mp dryrun world"), not an install flag -- "--dry-run"/"--dryrun" is not recognized by parse_flags (the shared flag parser every command including install uses), so passing it to "mp install" does NOT dry-run the install; it's silently left in @ARGV and mp will most likely try to treat it as a package name and fail confusingly. "mp dryrun" resolves dependencies/conflicts/HOLD/MASK/keywords the same way a real install would and stops there -- it does NOT run staging, patch application, phase scripts, hooks, or the real file-path-overlap conflict detector (find_file_conflict only ever runs deep in the real install path), so "would install: X" means "X's deps resolve cleanly," not "a real mp install X right after this definitely succeeds."
 
[h2]still stuck?[e]
 
"mp verify" checks the whole tree parses with no dependency cycle -- a good first step if something's behaving strangely across many packages at once, not just one. "mp dryrun X" resolves without installing anything, useful for seeing the whole planned graph before committing to a real (and possibly slow) build -- see the entry just above for exactly what it does and doesn't check.