#Troubleshooting
Errors already met while bringing Aegis up, with the fix that made them go away.
#Installer
| Message | Cause and fix |
|---|---|
build profile not found: …/storage/data/apps/<app>/build.toml | deploy.sh excluded storage; it now ships storage/data and excludes only storage/{apps,temp,media} |
ModuleNotFoundError: app.modules.thor.context | relative import depth; installer/core/tasks/* needs ...context, not ....context |
Can't instantiate abstract class PrepareTask | build tasks were missing run() |
E: Unable to locate package x | empty apt index; install_packages refreshes the index before installing, only when something is missing |
named-checkconf / libisc…so not found | tools live in bin/ and need LD_LIBRARY_PATH; the cube handles both |
no version information available (libpcre2) | cosmetic warning from a locally built pcre2 |
#Runtime
| Message | Cause and fix |
|---|---|
aegis: bundled Python runtime not found | fresh server: ./bin/aegis-prepare |
python.sha256 attribute error | old archive_ready() after the multi-arch change; use python.artifact().sha256 (fixed) |
CMake 3.24 or higher is required. You are running 3.22.1 | distro cmake is too old; the runtime ships cmake 3.31.6 |
meson.build:2040: ERROR: Expecting endif got string | distro meson 0.61 cannot parse modern syntax; the runtime ships meson 1.7.2 |
No CMAKE_CXX_COMPILER | g++ was missing from the toolchain |
stdio.h / limits.h not found | libc6-dev missing; the headers task installs it, and packages.installed() now compares the status string instead of searching for “installed” |
#Build
| Message | Application | Fix |
|---|---|---|
make: No targets specified and no makefile found | redis | the catalog had two entries named redis; catalog.by_name() prefers the standalone one over the PECL module |
No targets specified | vsftpd | the Makefile has no all target; targets = [] |
undefined reference to cap_init | vsftpd | libcap lives in the multiarch dir; patch adds /usr/lib/*/libcap.so |
assignment discards const / memchr | beanstalkd | modern-toolchain.patch drops -Werror and fixes the SIGTERM handler signature |
long long reliability test 1 | gmp | GCC 15 defaults to C23; profile sets CFLAGS=-O2 -std=gnu17 |
cannot find install-sh | opendkim | git snapshot without autotools helpers; pre = [["autoreconf", "-fi"]] + autoconf/automake/libtool |
cmilter not found | opendkim | libmilter-dev |
no strlcpy/strlcat | opendkim | libbsd-dev |
dependency "libuv" not found | bind | libuv1-dev |
liburcu-cds / lmdb / libcap | bind | liburcu-dev, liblmdb-dev, libcap-dev |
Dependency "cmocka" not found | bind | -Ddeveloper=enabled enables tests; removed |
No <db.h> include file found | postfix | either libdb-dev or -DNO_DB; we use -DNO_DB (spelled with the D!) |
default_cache_db_type=btree | postfix | add default_database_type=lmdb default_cache_db_type=lmdb |
rpcsvc/ypclnt.h | postfix | -DNO_NIS |
pcre.h not found | postfix | -DHAS_PCRE=2 for PCRE2 |
passwd file entry for postfix | postfix | [system] groups = ["postdrop"] users = ["postfix"] |
undefined reference to SharpYuv* | imagemagick, php | libwebp 1.6 ships SharpYuv separately: LIBS=-lsharpyuv |
expat.h not found | git | libexpat1-dev |
cargo: not found | git | NO_RUST=YesPlease |
SSL_get0_group_name@OPENSSL_3.2.0 | git | git assigns LDFLAGS; pass LDFLAGS= with our library paths on the command line |
No such file or directory: './configure' | freetype | the GitHub archive lacks the dlg submodule; use the official release tarball |
git submodule update fails | freetype | same cause |
aegis-local.conf + zone loop | bind | --libdir=lib keeps OpenSSL out of lib64 |
| brotli library missing | nginx | ngx_brotli builds brotli sources from its own deps/; module not enabled by default |
us->default_port | nginx | upstream-fair is incompatible with nginx 1.30; dropped |
location directive is not allowed here | nginx | snippets must not be included at http level |
invalid host in upstream "/aegis/run/php/php-fpm.sock" | nginx | unix sockets need unix: in fastcgi_pass |
open() "…/fastcgi_params" failed | nginx | include {{nginx_prefix}}/conf/fastcgi_params |
getpwnam("aegis-www") failed | nginx | worker account is created by configure |
mkdir() "…/nginx/cache" failed | nginx | cache directory is created by configure |
unknown geoip2_data_country_code | nginx | the variable only exists with a database; the log uses - when it is absent |
#Cubes and certificates
| Message | Fix |
|---|---|
no TSIG key at …/keys/tsig.key | run aegis cubes bind configure first |
rndc reload failed | named is not running, or controls/key mismatch |
certbot failed with dns_rfc2136 errors | zone missing in BIND, TSIG mismatch, or NS not delegated |
Aegis reported success but <name> is missing | certbot wrote to another config-dir; check certbot.data_dir and cli.ini |
ssl ensure fails with openssl.cnf | the bundled OpenSSL has no ssl/ directory; OPENSSL_CONF falls back to /etc/ssl/openssl.cnf |
#Panel, tasker and live feed
| Message | Cause and fix |
|---|---|
no action registered as <name> | the tasker is running code from before that action existed: Management → Tasker → Restart tasker |
a task stays running after a crash | it was marked interrupted on the next start; look at the log, then Retry |
aegis-tasker exited immediately in keeper.log | two starts raced and one lost the lock; the keeper now reports the live pid instead. If it repeats, check for two daemons: pgrep -x aegis-tasker |
| the task window shows nothing during work | the window was minimised: click the bar; the bell still counts |
| the dashboard tables blank out after a few seconds | pulse could not read the keeper registry; aegis pulse status shows what each area published |
| a page never updates | the WebSocket is down or unauthorised: check aegis keeper status for aegis-r-bird, reload the page for a fresh token |
a vhost answers 403 while the panel looks correct | the web account cannot reach the document root: aegis sys perms --path <root> --check, then --fix |
| the panel shows old values after a deploy | /assets/ is no-cache, so a plain reload is enough; if the data is old, the panel process is old: aegis web-admin restart |
| a new utility class has no effect | the CSS is prebuilt; add the rule to both css/app.css and src/app.css |
#Debugging tips
# what is installed whereaegis thor apps | headaegis keeper services# build output of one appaegis install nginx # up to 12 lines of the failing command# traces# platform logs: <root>/logs, i.e. aegis.logs_dir/etc/aegis/storage/logs/installer.log # one line per step/etc/aegis/storage/logs/keeper.log # supervision actions/etc/aegis/storage/logs/pulse.log # what the live feed sampled/etc/aegis/storage/logs/tasker.log # the queue daemon/etc/aegis/storage/logs/web-admin.log # the panel# application logs: /aegis/logs, written by the daemons themselves/aegis/logs/nginx/error.log # nginx startup problems#Deploy quirks
deploy.sh needs --full to ship the runtime; without it a fresh server hascode and vendor but no interpreter.
tar fallback exists for servers without rsync; excludes are anchored(/storage, ./storage) so vendor/apps/runtime still ships.