Skip to content

Troubleshooting

Problems while installing, and those of one system only, are on the page of that system, under “If it gets stuck”: Install on Windows, Install on Mac and Install on Linux. For example: virtualization, Ubuntu and the scheduled task on Windows; a Mac that sleeps; curl, root, systemd and linger on Linux. This page has what can happen on every system once the agent runs.

ProblemFix
The dashboard does not openCheck the logs (below). Another program may use the port: run ./install.sh again in the foxleague-agent folder and pick another one.
“The dashboard could not start: port … is used by another program”The agent says this once, in the logs and on Telegram. Your agents keep playing without the dashboard, and the agent tries the port again every minute. Close the other program or choose another port. For another port run ./install.sh again in the foxleague-agent folder; you can also set WEB_UI_PORT in .env and restart the agent.
The dashboard asks for the login although I am signed inThe dashboard may be open in two browsers, for example a tab inside an editor and your default browser. Each has its own sign-in, so the page the installer opens can ask for the login although another tab is signed in. Log in there too.
“The AI key is missing” bannerAdd your Anthropic key in Keys (Your keys). Without it your agents only watch.
Go LIVE is greyThis computer does not allow live signing yet: set AGENT_LIVE_ENABLED=1 in the .env file in the foxleague-agent folder and restart the agent.
Nothing happens at nightEach agent plans only inside its active hours (08:00 to 20:00 UTC by default). Change them in Settings, Timing.
“refused” in the ActivityAn action did not fit the game rules or your limits; the line says why. The agent adapts on its next cycle. Raise a limit only if you mean it.
A refusal “the MultiversX network has produced no block since …”The MultiversX network stopped producing blocks (it happens rarely, for minutes or hours), so the agent signs no payment into it; lineups, training and casual games go on. Nothing has to be done: each plan checks again and pays as usual once the network is back. If the network is fine on the explorer and the refusal says “ahead of this computer’s clock” or names a time long past, check this computer’s clock: it is more than a minute off. “could not be read” means the gateway (MVX_GATEWAY_URL in .env, MultiversX’s public one by default) did not answer.
Telegram stays silentBy default Telegram sends only the morning summary and urgent messages; send /updates all for every plan and result as it happens. If nothing arrives at all, press Test keys in Keys; if the chat is not linked, press Link my Telegram and send the code to your agent’s Telegram account.
“AGENT_MNEMONIC is set in this terminal and its recovery words are not the ones in …/.env”./run.sh was started in a terminal that has recovery words of its own (export AGENT_MNEMONIC=..., often from another project). They would win over your .env and the agent would start with another wallet than the one the installer showed. Type unset AGENT_MNEMONIC and start it again. The words are never printed; ./cli.sh uses the words of your .env whenever it has some (a .env without words, as in a container that passes them in, takes the words given, for ./run.sh too).
“foxleague-agent already runs on this data folder”A second copy was started while the agent runs, for example ./run.sh in a terminal next to the background service. It does not start, because two copies would plan and pay for every agent twice. Use the one that runs (its dashboard or Telegram) or stop it first. If you are sure that no other copy runs, delete the file the message names and start again.
“The update to … did not start and was undone”The new version did not stay up, so the agent went back to the version that ran before. Nothing of yours changed and nothing has to be done: the agent keeps playing on the version it ran. To try that version again later, press Try again in the dashboard’s notice or send /upgrade; if it is undone again, keep the version you run and tell the maintainers what the logs (below) say.
“The update to … was not installed: this system’s tar cannot unpack inside the agent’s background service”The background service of an install made by an older installer refuses a call that the tar of Ubuntu 26.04 needs to unpack an update. Run ./install.sh --update once in a terminal, in the foxleague-agent folder: it installs the update outside the service and takes that one line out of the service’s file, so later updates are one click again. Pasting the install line again does the same. On Windows, open Ubuntu first: wsl -d Ubuntu --cd ~ in PowerShell, then cd foxleague-agent. Until then the dashboard’s notice offers no Update now: it would fail the same way.
“The update to … was not installed: the archive could not be unpacked (tar: …)”What tar said is in the brackets; its first lines are in the logs (below). A full disk is the usual reason: free some space, then press Try again in the dashboard’s notice.
“Version … is in place and runs from the next start”The agent was started by hand with ./run.sh (an install made with --no-service), so nothing starts it again after an update. The new version is in place and the agent keeps playing on the version it runs: stop it (Ctrl-C in its terminal) and run ./run.sh again in the foxleague-agent folder (Update).
“No update was started: …”The answer names the reason: “you run …, the newest version”; “an update is already being installed” (wait a minute or two); “the last update is still being confirmed, try again in a minute” (the version you just installed has to stay up for 45 seconds before the next update is taken); “updates are switched off on this machine (AGENT_UPDATE_CHECK=0)” (remove that line from .env and restart, or update in a terminal); “the release server could not be asked” (GitHub or your connection, try again later); or what this install does instead, such as ./install.sh --update for a git checkout (Update).
The update notice never appearsThe agent asks GitHub about every 10 minutes and only tells you of a release that is signed and newer than yours. Press the round arrow next to the version in the dashboard (Check for updates) or run ./cli.sh update-check in the foxleague-agent folder to ask now. With AGENT_UPDATE_CHECK=0 in .env it never asks.
“FoxLeague’s manual changed since the agents’ copy (pages: …)”FoxLeague changed its player manual after the copy your agents play by was made. Nothing is broken: the agents keep playing by their copy. The maintainer runs sync-manual and publishes a version with the new manual; update when it is out (Update). The agent checks the new copy the same day.
“Could not check FoxLeague’s manual today: …”The check could not read FoxLeague’s manual; the line says why (FoxLeague did not answer or the copy has no page record that belongs to it; sync-manual writes one). It is not taken as up to date. The agent asks again each hour, up to four times a day, then the next day; ./cli.sh manual-check in the foxleague-agent folder asks at once.
“This dashboard is not served at that address”The dashboard answers only at this computer’s own names (http://localhost:8870), at an address written as numbers and at WEB_UI_HOST, so a website cannot point its own name at it. Open it at http://localhost:8870 (or the port you chose). To open it at another name, add that name to WEB_UI_HOSTNAMES in .env (names separated by commas) and restart the agent. Behind nginx set WEB_UI_TRUST_PROXY=1.
“FoxLeague changed the shape of routes the agents call since their copy (routes: …)”FoxLeague changed what one of the routes your agents call sends or answers, by its own API description. Nothing is broken: a field the agent cannot read makes it refuse that action, never guess. A version of the agent checked against the new shapes follows; update when it is out (Update).
A refusal “paused by the owner’s choice: FoxLeague changed its manual page …”You chose also pause the actions whose rules changed in the Strategist · all agents box and FoxLeague changed that page since your agents’ copy. The action runs again once a version with the new copy is installed or when you go back to tell me only (it asks for your password) (Update).
“FoxLeague’s game settings changed since the agents’ copy (keys: …)”FoxLeague added or removed a game setting after the copy your agents play by was made, usually with a new rule. Nothing is broken: each plan reads the live values and is told of the change. A version of the agent that knows the new setting follows; update when it is out (Update).
The agent does not start after I changed the recovery wordsThe logs say “The recovery words … are not the ones this install’s agents were made with”. Put the original words back in .env and restart the agent. To play another wallet’s FoxLeague team, keep the original words and use Import team (Import your team). To start over with the new words, stop the agent and move data/agent.db, agent.db-wal and agent.db-shm to another folder: history and settings start fresh, so do it only when the old agent wallets are empty or you keep their words. Replacing pem/agent1.pem changes nothing for the agent: it signs with the words, the PEM file is only for you to log into FoxLeague.
WhatLinux and Windows (WSL2)macOS
Logsjournalctl --user -u foxleague-agent -ftail -f data/service.log
Restartsystemctl --user restart foxleague-agentlaunchctl kickstart -k gui/$(id -u)/ai.foxleague.agent

The Linux commands work from any folder. The commands that start with ./ (./install.sh --update, ./cli.sh and ./install.sh --uninstall) and the Mac’s log are typed in the agent’s folder: go there first with cd ~/foxleague-agent. Type them as yourself, without sudo: as root on your folder ./cli.sh, ./run.sh and ./install.sh stop before they change anything and say so, because files of root there would keep the agent from starting again. An agent that a container or a service of your own starts as root there (one that mounts your install, a system unit without User=) still starts when it says FOXAGENT_SUPERVISED=1 (in .env or in its environment) and runs with no terminal. One whose own update already ran there as root starts too. On Windows they are typed inside Ubuntu: open it with wsl -d Ubuntu --cd ~ in PowerShell. The uninstall on Windows is one line in PowerShell (Install on Windows).