--- url: https://docs.codefox.ai/self-host/troubleshoot.md --- # 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](/self-host/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 ` for one command. * On the server itself: `FOXDEN_LOCAL=1 foxden ` (with `sudo`: `sudo FOXDEN_LOCAL=1 foxden `). ### 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](/self-host/plan). ### The server is too small `... below the baseline tier floor` with ` 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](/reference/sizing). ### 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 /tcp`) and run `foxden init --resume`, or install from your computer with `foxden init --host :`. ### 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 `, 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. 1. Reload the address: a certificate often arrives within about 30 seconds of the first visit. 2. Check that the `*.your-domain` record points at the server. 3. 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. 4. On the server, run `docker compose --project-directory /opt/foxden/ingress logs caddy` to see the certificate error (for Arctic on its own, `foxden logs caddy --product arctic`). 5. Run `foxden doctor` to 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 ` to see which container is down, and `foxden logs app --product ` for why. `foxden restart --product ` 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 ,admin` to connect it, or give the app its own **People** page back with `foxden config set PEOPLE_MANAGED_BY --product `. ### 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](/self-host/running-arctic). ## Updates and backups Update messages (rolled back, rollback failed, disk, pull token, already in progress) are on [Update and restart the apps](/self-host/update). Backup and restore messages (passphrase, local only, scheduled twice) are on [Back up and restore](/self-host/backup). Also: ### No backup yet `no backup artifact in .../backups`. The schedule has never produced a backup. Run `foxden backup --now --product ` 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/-backup.log`. ### A restore stopped * `... does not look like an archive from `: 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 run `foxden doctor` again. ## Getting help Run `foxden support-bundle --product ` 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](/self-host/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.