Fixing Broken pkg and Ports Builds on FreeBSD
pkg install fails, or a port won't build. Here's a systematic way to tell whether it's a stale catalog, a broken dependency, or a genuinely broken port.
pkg install somepackage fails with a dependency error, or make install inside a ports directory dies partway through a build. Before assuming the package or port itself is broken, work through the more common, easily-fixed causes first.
Step 1: refresh the catalog before anything else
A stale local package catalog is the single most common cause of confusing pkg errors — “no such package” for something that clearly exists upstream, or a dependency resolution failure for versions that were updated after your last sync:
pkg update -fThe -f flag forces a full catalog refresh even if pkg thinks its local copy is still current — worth using explicitly when something feels wrong rather than trusting the automatic staleness check.
Step 2: check for a genuinely broken or held package
pkg check -d
pkg version -vpkg check -d verifies that every installed package’s declared dependencies are actually satisfied on disk — this catches a half-completed previous upgrade before you try to layer a new install on top of an already-inconsistent state.
Step 3: for ports builds, check the actual build log, not just the summary
A port build failure’s real cause is almost always further up in the build output than the final error line shown in the terminal:
cd /usr/ports/www/nginx
make install clean 2>&1 | tee /tmp/build.logSearch that log for the first Error or *** line, not the last — build systems often cascade a single early failure into several confusing downstream error messages.
Step 4: check for an outdated ports tree
If a port references a distfile URL or version that no longer exists upstream, or fails against a dependency’s newer version in a way a ports-tree update would fix, refresh the tree itself:
portsnap fetch update
# or, if using the Git-based tree:
cd /usr/ports && git pullStep 5: check for a mismatched dependency built via a different method
Recall that ports and pkg share the same underlying package database — a common failure mode is a dependency installed via pkg with default OPTIONS, while the port you’re building expects that same dependency built with a different set of options enabled. pkg info -A lists which packages were installed as automatic dependencies versus explicit requests, useful for spotting one that might need rebuilding from source with different options:
pkg info -A
make config-recursive
make install cleanmake config-recursive walks the entire dependency tree and lets you review/set build options for every port in the chain, not just the top-level one — often the fix when a specific compile-time option is what a build is actually failing on.
Step 6: distfile corruption
If a fetch succeeded but the resulting file is corrupted or incomplete (an interrupted download, a mirror serving a stale copy), clear the cached distfile and let the port re-fetch it:
rm /usr/ports/distfiles/nginx-*.tar.gz
make fetchA sane order of operations
Working through these in order — refresh the catalog, verify installed-package consistency, read the actual build log’s first error, refresh the ports tree, check for options mismatches, and finally check distfile integrity — resolves the overwhelming majority of “pkg/ports just doesn’t work” situations without needing to guess or reinstall the whole system.