I run thick jails on my FreeBSD homelab server, and I hit this error more often than I’d like:

$ pkg bootstrap
Bootstrapping pkg from pkg+https://pkg.FreeBSD.org/FreeBSD:14:amd64/quarterly, please wait...
Verifying signature with trusted certificate pkg.freebsd.org.2013102301... done
[your-jail.ripley.home.arpa] Installing pkg-2.7.5...
Newer FreeBSD version for package pkg:
To ignore this error set IGNORE_OSVERSION=yes
- package: 1404000
- running userland: 1402000
Ignore the mismatch and continue? [y/N]:

The funny thing was, this happened even after bootstrapping a fresh thick jail, starting from scratch with a fresh ZFS dataset and only after running bsdinstall. Even after setting up everything from scratch, I still got that dang error. How could that be?

Why this happens even in freshly-created jails

It turns out that bsdinstall doesn’t grab fresh userland files each time you run it. The first time you run it, it saves cached copies of the files it downloads into /usr/freebsd-dist. Subsequent runs will use these files first, no matter how long it’s been since the files were downloaded.

On my machine, I had first started bootstrapping jails back on 14.2. But, my system is now running 14.4. That’s why every time I created a fresh jail, I always encountered this issue.

Clearing the files from /usr/freebsd-dist and then re-running the jail creation routine bootstrapped a fresh thick jail without this mismatch.

What the error means

pkg is telling you that the repos you’re pulling from are for 14.4, but the userland you’re running is older.

In the example above:

• package: 1404000 → The packages are built for FreeBSD 14.4
• running userland: 1402000 → The jail’s userland is running FreeBSD 14.2

The fix

Don’t just set IGNORE_OSVERSION=yes!

It’s tempting to just answer y and move on, but there’s a reason why N is the default choice. Installing packages compiled for a version of the OS that’s newer than what’s running can introduce all sorts of problems, some that might not be immediately obvious.

Clear the stale distribution cache

The best solution is to delete the stale cached files, allowing bsdinstall to download fresh copies.

rm -rf /usr/freebsd-dist/*

Try to run the pkg bootstrap process again, it should work.

pkg bootstrap

If you can’t rebuild the jail but want to fix the problem in-place

In my case, I’m bootstrapping a fresh jail, so it was easy to just destroy it and make a fresh one.

But in the case when you have an existing jail that already has this issue, and you want to try and repair it, here’s the fix I use. Run these commands from outside the jail, on the jail host:

Psst… If you’re coming here from the future and you’re running a version newer than 14.4, you’ll obviously want to update these commands to suit your environment.

# Run the initial upgrade pass
doas freebsd-update -b /your-jail-path/your-jail --currently-running 14.2-RELEASE -r 14.4-RELEASE upgrade

# Install it
doas freebsd-update -b /your-jail-path/your-jail --currently-running 14.2-RELEASE -r 14.4-RELEASE install

# Restart the jail
doas service jail restart your-jail

# Run the second upgrade pass, cleans up old files
doas freebsd-update -b /your-jail-path/your-jail --currently-running 14.2-RELEASE -r 14.4-RELEASE install

# Restart the jail again
doas service jail restart your-jail