Package Troubleshooting

Purpose

Diagnose package-manager failures without treating every error as a reason to reset repositories or run a broad upgrade.

When to use

• pkg or apt fails to resolve, download, verify, or configure a package.
• A package name from Debian or Ubuntu does not exist.
• A binary fails with CANNOT LINK EXECUTABLE or a missing .so after an upgrade.

When NOT to use

• Compile or wheel failures after the package manager succeeded: use python-native-build or node-native-build.
• Inside proot: that side has its own apt; use proot-boundaries first.
• Do not run pkg upgrade, change mirrors, or clear package state before capturing the exact error.

Preconditions

Capture, read-only: the full error, the requested package, dpkg --print-architecture, the current date, and free space. sh scripts/check-pkg-state.sh collects these without secrets.