Package will not install: download, architecture, dependencies, LuCI and postinst

Outcome

Tell whether the package is missing from the feed or exists but fails to install;
Identify architecture, ABI, dependency, LuCI frontend or postinst failure;
Understand why the main program installed but LuCI has no menu;
Recover without reflashing the firmware.

Layer 0: record the environment

Router shellRecord firmware, architecture, package manager and feeds

ubus call system board
cat /etc/openwrt_release
cat /etc/apk/arch 2>/dev/null
command -v apk
command -v opkg
cat /etc/apk/repositories.d/distfeeds.list 2>/dev/null

25.12 uses apk; 24.10 uses opkg. Do not rename .ipk to .apk, and do not force another architecture.

ExpectedYou know whether to use apk or opkg, and the release/target/arch.

Layer 1: download and feeds

Router shellConfirm the package exists in the feed

apk update
apk search <package>
apk info -e <package>

If apk update fails, check 404/signature/time/certificates first. If search finds nothing, the feed may be stale, the name may be wrong, or the package is not in this release/arch.

Expectedapk search/update finds it, or you know it is absent.

Router shellCheck format/checksum before installing

25.12: .apk; 24.10: .ipk;
Prefer feeds over cloud-drive/forum “repacks”;
For local files, verify SHA-256/signature;
Do not routinely use --allow-untrusted; it bypasses trust checks and does not prove compatibility.

ExpectedThe source is trustworthy and the format/arch matches.

Layer 2: architecture and ABI

Router shellVerify package architecture, not filename

cat /etc/apk/arch
apk info -a <package> | grep -E "arch|depends|provides" | head

x86_64, aarch64_cortex-a53, etc. are not interchangeable;
kernel modules (kmod) must match the kernel version/ABI;
script-only packages may be any/noarch and cannot prove architecture rejection.

This lab downloaded an aarch64 sqm-scripts, but it is sqm-scripts-any (no architecture-specific binary), and local --allow-untrusted still replaced it. That does not prove architecture checks passed. A real rejection test needs an ELF-bearing package; this page does not mark it verified.

ExpectedThe package arch matches /etc/apk/arch; kmods also match the kernel.

Layer 3: dependencies

Router shellRead the dependency tree and install output

apk add <package> 2>&1 | tail -20
apk info -R <package> 2>/dev/null | head -20
apk info -e <dependency>

Common cases:

main program installed, luci-app-* missing;
kmod-* does not match the kernel;
dependencies live in another feed/version;
official/ImmortalWrt/iStoreOS feeds are mixed.

ExpectedMissing dependencies have concrete package names.

Router shellMain program ≠ LuCI frontend

apk info -L <luci-app-name> | head -20
ls -l /usr/share/luci/menu.d/ 2>/dev/null | grep <name>

This lab:

sqm-scripts only: installed, but no LuCI menu;
add luci-app-sqm: /usr/share/luci/menu.d/luci-app-sqm.json and /www/luci-static/resources/view/network/sqm.js appeared;
remove luci-app-sqm: menu file disappeared; reinstall restored it.

If the menu still does not show: clear browser cache, log out/in, check luci-base/language pack/rpcd; do not reflash first.

ExpectedAfter installing luci-app, menu/static files appear.

Recorded demo (017 lab)

017 lab: sqm-scripts → luci-app-sqmDownload .cast

Real OpenWrt 25.12.6 VM session: install sqm-scripts (no LuCI menu), add luci-app-sqm (menu file appears), remove it (menu disappears), reinstall (restored). The player is a supplement; the code blocks in this page are authoritative.

Layer 5: postinst / setup scripts

Router shellPackage installed but service/config did not

logread | tail -50
apk info -L <package> | head -20
ls /etc/uci-defaults/ 2>/dev/null | tail

A failed postinst does not necessarily roll back the package;
check /etc/uci-defaults, /etc/init.d/<service>, /etc/config/<service>;
do not force-reinstall repeatedly just to rerun postinst; read the log/scripts first.

ExpectedYou know whether postinst failed and what it changed.

Layer 6: recovery

Router shellUninstall/restore feeds/reboot instead of reflashing

apk del <package>
# if feeds were changed:
cp /etc/apk/repositories.d/distfeeds.list.bak.YYYY-MM-DD /etc/apk/repositories.d/distfeeds.list
apk update
reboot

If the package breaks management, stop the service/restore config backups first; reflashing is the last resort.

ExpectedBack to the previous state, or at least able to continue debugging.

Common failures

Symptom	More likely cause	Check first
`apk update` 404	wrong release/target/arch/mirror path	feed files + `curl -I`
Package not found	wrong name/feed/version	`apk search`
Downloaded but will not install	arch/dependency/signature	`apk info -a`, install output
Installed but no menu	only main program, no `luci-app-*`	`apk info -L`
Menu exists but fails to open	LuCI/language/rpcd/cache	browser console, `logread`
postinst error	script/permissions/dependency/config	`logread`, `/etc/uci-defaults`
No internet after install	service changed DNS/firewall/interface	stop service, restore backups

E2 lab run (2026-10-20)

Environment: OpenWrt 25.12.6 x86 VM 200; x86_64; apk; TUNA mirror for speed (the page does not require it).
sqm-scripts 1.7.2-r1: installed; no LuCI menu/controller.
luci-app-sqm: installed; /usr/share/luci/menu.d/luci-app-sqm.json appeared; /www/luci-static/resources/view/network/sqm.js exists.
apk del luci-app-sqm: menu file disappeared; reinstall restored it.
aarch64 sqm-scripts: package is sqm-scripts-any (noarch); local --allow-untrusted accepted it; not an architecture-rejection test.
Not reproduced destructively: postinst failure, kmod ABI mismatch, real architecture-specific rejection.

E2 status and sources

This is E2 partial: install/dependency/LuCI menu/remove-reinstall were tested; architecture rejection/postinst failure were not fully reproduced.
Recipe: tests/recipes/plugin-install-25.12.md.
Do not turn this into “every package installs”; verify release/target/arch per package.

Sources

Router.Homes

Independent OpenWrt notes. Every page states the firmware, device, package manager and way back.

Icons: Solar by 480 Design, CC BY 4.0