Resolve a package repository or ABI mismatch

Synopsis #

An ABI or repository error usually means that the installed userland, effective pkg ABI, enabled repository, package branch, or upgrade phase does not agree with the others. Changing ABI, OSVERSION, or a repository URL can suppress a useful safety check and install unusable packages.

Collect the evidence first. Command-line ABI overrides belong only in a release procedure that explicitly requires them, such as the documented 15.0 pkgbase upgrade to 15.1.

Record the four identities #

Capture the running kernel, installed kernel, installed userland, machine architecture, and effective package configuration:

$ freebsd-version -kru
$ uname -m
$ uname -p
$ pkg -vv
$ pkg repositories

Then determine whether the base system itself is packaged:

$ pkg which /usr/bin/uname

Finally, inspect the architecture recorded on representative installed packages:

$ pkg info pkg

Save the complete failing command and error. Phrases such as “wrong architecture,” “repository does not contain packages,” “newer FreeBSD version for package,” a missing catalogue, and an unexpected mass removal describe different failures.

Classify the mismatch #

Confirm that the installed release remains listed on the supported-release page . An archived repository is not a maintenance strategy for an end-of-life host.

Inspect repository overrides #

Review files under /etc/pkg/ and /usr/local/etc/pkg/repos/. Release-supplied configuration belongs under /etc; local overrides belong under /usr/local/etc/pkg/repos/.

Look for:

• a hard-coded architecture instead of ${ABI};
• a quarterly/latest path inconsistent with the intended policy;
• a fixed old release or package mirror;
• multiple enabled repositories supplying the same package origins;
• a kernel-module repository for a different release or ports branch;
• a global ABI or OSVERSION setting added as an earlier workaround.

The quarterly or latest guide describes a controlled branch change. The broader packages, ports, or poudriere guide explains when a private repository is the maintainable answer. When the evidence points to routing or availability rather than ABI policy, preserve automatic fallback with the download and package mirror guide .

Refresh metadata after correcting policy #

After the release, ABI, and repository configuration agree, force a catalogue refresh and perform a dry run:

# pkg update -f
# pkg upgrade -n

Inspect all removals, replacements, repository changes, and downgrades. Do not proceed when the transaction still proposes unexplained broad removal.

Check package-database dependencies separately:

# pkg check -d -a

This detects missing package dependencies; it does not prove that a third-party kernel module matches the running kernel or that a service can restart.

Complete a major ABI transition #

After a distribution-set upgrade between major FreeBSD versions, the official Handbook requires installed third-party packages to be replaced for the new ABI and documents:

# pkg-static upgrade -f

Use that command only at the package phase of the corresponding release upgrade, after the new base userland is installed. For the current target, follow the 15.1 upgrade checklist and the official 15.1 instructions. Do not use a forced reinstall as the first response to a network or branch error.

Escalate with a reproducible record #

When the corrected configuration still fails, retain:

• freebsd-version -kru and uname -mp;
• the repository portion of pkg -vv;
• pkg repositories;
• the complete pkg update -f output;
• the exact upgrade phase and source release;
• whether the host uses distribution sets, pkgbase, or a source-built base.

Remove credentials and private repository tokens before sharing the record.

Primary references #

• FreeBSD Handbook: package repositories and package branches
• FreeBSD Handbook: packages after a major-version upgrade
• FreeBSD 15.1-RELEASE upgrading instructions
• pkg(8)
• pkg.conf(5)
• pkg-repositories(8)
• pkg-check(8)