Fix server problems
This page lists the messages foxden prints when something on the server is wrong, what each one means and what to do. Messages are quoted as the tool prints them, with ... where it fills in a name or number.
When you cannot tell what is wrong, start with foxden checkup, then foxden doctor --fail-only. See Check the server's health.
Reaching the server
foxden says no box is named
The command stops with ... a Linux server, and no box is named (or and this machine is a Mac). Server commands run on a server, never on your own computer. Do one of:
foxden connect user@host, then run the command again.foxden --host user@host <command>for one command.- On the server itself:
FOXDEN_LOCAL=1 foxden <command>(withsudo:sudo FOXDEN_LOCAL=1 foxden <command>).
Connected without root
foxden: connected to ... as a non-root user without passwordless sudo: anything that needs root will fail. Connect as root, or give that user passwordless sudo (NOPASSWD in its sudoers line).
Before the install
foxden init checks the server before it asks anything. A failed check stops it with nothing changed.
not running as root
not running as root. Run it with sudo, or connect as root.
Ports 80 and 443 are taken
already in use by something that is not a foxden stack: 80 (the shared ingress needs it). Another web server (often nginx or Apache) holds the port. Find it with ss -tlnp, stop and disable it, then run foxden init again. The same message names an app's own port, such as 3010 (Fennec's upstream), when something else listens on it; the ports are listed in Plan your server.
The server is too small
... below the baseline tier floor with <App> needs at least ... vCPU / ... GB RAM / ... GB disk. The message names the one dimension that is short. Resize the server, free disk space, or install fewer apps. See Server sizes.
ghcr.io cannot be reached
could not reach https://ghcr.io/v2/ over HTTPS. The app images come from there. Allow outbound HTTPS (port 443) to ghcr.io in your network or the provider's firewall.
Docker is too old
engine ... is below the 24.0.0 floor, or compose ...: below the 2.20.0 floor. The Docker that comes with the distribution (docker.io) is too old. Install Docker CE from docker.com, then run foxden init again.
Not a supported system
no supported package manager found, or armv7l: foxden publishes x86_64 and aarch64 only. Use Ubuntu or Debian on a 64-bit server. On RHEL, Rocky, Alma, Fedora, Alpine or Amazon Linux, install Docker and its Compose plugin yourself first.
During the install
The DNS record is missing
These names do not point at this server yet. Where you manage the domain, create: followed by the record. Make the A record shown, then choose wait, or quit and run foxden init --resume once it is live.
The firewall is not turned on
refusing to enable the firewall; this session is over SSH and nothing on this box says which port sshd listens on. Your SSH server may use a port other than 22. Allow it first (ufw allow <port>/tcp) and run foxden init --resume, or install from your computer with foxden init --host <server>:<port>.
The registry refused the login
foxden init: the registry rejected those credentials. The registry username or pull token is wrong or expired. Get a new token from whoever gave you the first, then run foxden init --resume. Leave both blank for public images.
An app did not report healthy
foxden init: the stack did not report healthy at ... 2× in a row within 200s. The containers are up. The app started but did not answer. Read why with foxden status and foxden logs app --product <app>, fix it, and run foxden init --resume.
An address did not answer over HTTPS
The hand-over screen says ... did not answer over https. The apps run; the certificate is not there yet.
- Reload the address: a certificate often arrives within about 30 seconds of the first visit.
- Check that the
*.your-domainrecord points at the server. - Check that ports 80 and 443 reach the server from the internet. A cloud provider's firewall in front of the server blocks certificates without saying so.
- On the server, run
docker compose --project-directory /opt/foxden/ingress logs caddyto see the certificate error (for Arctic on its own,foxden logs caddy --product arctic). - Run
foxden doctorto check again.
Running
An app does not answer
foxden doctor says GET ... failed or timed out (or responded but reported unhealthy) on the health row. Run foxden status --product <app> to see which container is down, and foxden logs app --product <app> for why. foxden restart --product <app> starts it again.
The console cannot change server settings
foxden doctor says Admin is installed but its control service is not running: the console can show server settings and change none. Admin's pages show what is set without buttons. Run foxden update --product admin, which puts the control service back, then reload Admin. In Admin, the same problem shows as The server is not answering Admin.
An app refuses to start after handing its people to Admin
foxden doctor says PEOPLE_MANAGED_BY=admin without ... and that the app refuses to start until Admin is connected and enforcing. Run foxden init --products <app>,admin to connect it, or give the app its own People page back with foxden config set PEOPLE_MANAGED_BY <app> --product <app>.
A shared setting differs between apps
foxden doctor says an app's settings differ from /etc/foxden/suite.env, or that suite.env holds a setting the app does not. Run foxden suite sync to copy the shared value in (--force to replace the app's own).
Arctic's notetaker is signed out
foxden doctor warns on bot-session-age from day 10 (bot session is ... old, ...d until the 14-day wall) and fails from day 14. Sign the notetaker's Google account in again on Arctic's Connect page. See Running Arctic.
Updates and backups
Update messages (rolled back, rollback failed, disk, pull token, already in progress) are on Update and restart the apps. Backup and restore messages (passphrase, local only, scheduled twice) are on Back up and restore. Also:
No backup yet
no backup artifact in .../backups. The schedule has never produced a backup. Run foxden backup --now --product <app> and read its output, then foxden backup --verify.
The newest backup is old
newest artifact is ... old, but the schedule is .... The nightly backup stopped. Run foxden backup --now and read the script's own output; the log is /var/log/<stack>-backup.log.
A restore stopped
... does not look like an archive from <App>: the file is another app's backup. Pass the right--product.archive verification FAILED ...; refusing to touch the box: the backup is damaged or the passphrase is wrong. Nothing changed; try an older backup.doctor gate FAILED ...; restore completed but the box is not healthy: the data is back, but a check is red. Fix the rows above it and runfoxden doctoragain.
Getting help
Run foxden support-bundle --product <app> and attach the file to your question. It holds no setting values, but it does hold recent log lines. See Check the server's health.
An unexpected error prints something went wrong that this command did not expect; send that line and the command you ran with the support bundle.