Synopsis #
OpenBSD packages are built for a specific architecture and base-system branch. Most pkg_add(1) failures result from an unsupported release, an unexpected package source, a base/package mismatch, temporary snapshot lag, an unavailable package or flavor, or an interrupted transaction.
This guide preserves the first error, identifies the branch and source, and restores consistency before attempting repair. It does not use force flags, unsigned repositories, database deletion, or manual library copying as general remedies.
Preserve the First Failure #
Run the failing command once with verbose output and record the complete result. Repeated retries can replace the useful first diagnostic with dependency or partial-package errors.
# pkg_add -v PACKAGE_STEM
Replace PACKAGE_STEM with the requested package stem. Do not publish output that contains private mirror credentials, internal hostnames, or repository tokens.
Identify the Running System #
Record the kernel, architecture, and complete base-system identity:
$ uname -a
# Record the running kernel and architecture
$ sysctl kern.version
# Record the complete kernel build identity
$ arch -s
# Record the package architecture token
A release system, a -stable system, and a -current snapshot do not select packages in the same way. The kernel and base userland must also belong to the same supported system state. If an upgrade was interrupted, complete the official base-system upgrade procedure before repairing packages.
Inspect the Package Source #
The default package source derives from installurl(5) :
$ cat /etc/installurl
# Display the configured mirror base URL
$ env | grep -E '^(PKG_PATH|TRUSTED_PKG_PATH)='
# Detect environment variables that override the default source
An empty second command is normal. A stale PKG_PATH can silently select another release, a local directory, or an incomplete repository. Remove an unintended override from the calling environment or automation policy; do not rewrite /etc/installurl merely because one mirror request failed.
Test name resolution and the configured mirror independently. ftp(1) reports HTTP, TLS, DNS, and connection failures without changing package state:
$ ftp -o /dev/null https://cdn.openbsd.org/pub/OpenBSD/
A successful general request does not prove that a specific release and architecture directory still exists. Supported-release status and snapshot publication remain separate checks.
Distinguish the Failure Class #
No Installation Candidate #
Search the selected repository with pkg_info(1) :
$ pkg_info -Q PACKAGE_STEM
No result can mean that the stem is wrong, the package is unavailable on that architecture, the package moved or was removed, or the selected release no longer has a repository. Search by a shorter functional term and consult the current ports index. Do not download a package from another release or architecture.
When several branches or flavors match, select one of the choices reported by the current package tools. Do not copy a versioned filename from an older article.
Missing Shared Library or Version Mismatch #
A missing base library can mean that an installation set was omitted or that the base and package states differ. A missing package library can mean that only part of a dependency set was updated.
Review the system upgrade state and the installed package that owns the dependency. Do not create a compatibility symlink or copy a library from another host. On a release system, follow the release-specific upgrade page and then update all packages. On -current, update the base snapshot and packages as one coordinated maintenance event.
Snapshot Mirror Lag #
During a -current snapshot transition, the base snapshot and packages on a mirror can be temporarily out of sync. The official package FAQ recommends waiting for mirrors to catch up when that is the cause. Switching repeatedly among mirrors cannot create a package set that has not finished building.
Signature or Checksum Failure #
Stop on a signature failure. Confirm the system date, the exact repository, the installed package-signing keys, and whether a mirror transfer was incomplete. Do not use the unsigned or checksum-bypass controls to turn an unexplained verification failure into an installation.
Interrupted or Partial Package #
List partial registrations without deleting them:
$ pkg_info | grep '^partial-'
The package FAQ explains that a later successful installation can complete an interrupted package, or the partial package can be removed deliberately. Preserve the original error and confirm no dependent operation is still running before either action.
.libs-* packages retain shared libraries needed by installed or running software. They are not equivalent to abandoned temporary files and must not be removed by filename pattern.
Restore the Normal Update Sequence #
After the base system, architecture, and package source are correct, update the complete installed package set:
# pkg_add -u
Then retry the requested package by stem. Managing Software: Packages and Ports describes normal installation, removal, and dependency cleanup. Updating and Upgrading OpenBSD describes the required base-system sequence.
The -U option updates dependencies while adding a new package and can leave a partially updated set. It is not a substitute for restoring a consistent base and package branch.
Check the Package Database After an Interruption #
pkg_check(8) checks installed package registrations and can propose repairs:
# pkg_check
Read every proposed change. Back up /var/db/pkg before accepting a repair that changes registrations, and preserve the command output. Do not delete /var/db/pkg, edit packing lists by hand, or use pkg_add -D failsafe controls without diagnosing the exact invariant being waived.
Verify Recovery #
After the repair:
$ pkg_info PACKAGE_STEM
# Confirm the intended package is registered
# pkg_add -u
# Confirm the complete package set has no pending update failure
# pkg_check
# Confirm package registrations and files are consistent
Review package messages and restart only the services whose updated packages require it. Record whether the root cause was release support, source override, snapshot timing, package availability, an interrupted transaction, or an incomplete system upgrade so the same failure does not recur in automation.