Common problems

Start with Settings → System → Run health check. It asks your install the questions below and says what to do about each answer. If it does not explain what you see, download the diagnostics bundle and send it to support.

Some steps name commands that run on the machine of a self-hosted install. On the hosted version Reqursor runs the machine for you, so those steps are not yours to do: write to support instead.

The health check

Where to look

On a self-hosted install:

• A ticket's run: the ticket's page streams the run's events.
• The dashboard's own errors: Settings → System → Logs. An error message with an error id points at an entry there.
• Docker: in the deploy/ folder, docker compose logs -f worker for runs and docker compose logs -f web for the dashboard.
• Bare metal: journalctl -u reqursor-dev-worker -f for runs and journalctl -u reqursor-dev-web -f for the dashboard.
• Windows: the log files in C:\ProgramData\ReqursorDev\logs (web.log and worker.log, with .err.log files next to them).

To restart the worker: on bare metal, sudo systemctl restart reqursor-dev-worker. With Docker, in the deploy/ folder, docker compose up -d worker. On Windows, restart the ReqursorDevWorker Scheduled Task. A ticket that was running goes back to Ready, see Clock drift and crash recovery.

Setting up

The setup asks for a setup code. The web app prints it when it starts and keeps it in the file setup-code in the data folder until the Owner exists.

• Docker, in the deploy/ folder: docker compose logs web | grep "Setup code"
• Bare metal: sudo cat /var/lib/reqursor-dev/setup-code
• Windows, in an elevated PowerShell: type C:\ProgramData\ReqursorDev\setup-code

The code in your welcome email works too, once this install has activated your license. After 5 wrong codes from one address, wait 15 minutes.

On the hosted version, use the setup code from the email that brought your license key.

"Setup is running elsewhere". Another browser holds the setup session. Enter the setup code in this one to take setup over.

The browser warns about the certificate. When the install makes its own certificate, for example the Docker install with its TLS setting on internal, browsers do not know it yet. Trust it once per computer (the Docker install page says where to find it), or use a public certificate.

The license does not activate, or it says the license belongs to another install. An activation is tied to one install. To move a license to a new machine, take a backup, then choose Transfer license on Settings → License & billing on the old install. That deactivates it, so the license can be activated on the new one. If the old machine is gone, write to support. The install must reach license.reqursor.com over HTTPS.

Start with credits does not activate. It waits until the payment in the tab that opened is complete, and then the install claims the license by itself. If you closed the tab, start again.

Installer problems

• The Windows installer stops at once. Open the app called Windows PowerShell (version 5.1) as Administrator. The newer PowerShell 7 does not work. See Windows.
• The Windows installer says Git is missing and winget is not available. The installer installs Git with winget when it is missing. Install Git yourself first, then run the installer again.
• The dashboard cannot be reached from another computer on Windows. Without the -Tls option the dashboard listens on 127.0.0.1 only, in plain HTTP, so it is reachable from that machine alone. Use -Tls, or put a reverse proxy of your own in front of it.
• The installer on Ubuntu complains about a security profile. Ubuntu 23.10 and newer restrict what the agent sandbox needs. The installer adds Ubuntu's profile for it. If that profile is missing, install it with apt install apparmor-profiles and run the installer again.
• docker compose up fails with "set REQURSOR_DEV_VERSION". Set it in your .env file to the version of the image you built.
• Addresses clash with networks you already have. Change the subnets and the fixed addresses together in .env.
• The dashboard does not start because its port is already in use. On a bare-metal or Windows install the dashboard uses port 8765. Stop the other program that holds that port, then restart the web service.

Signing in

• "Too many sign-in attempts". 5 failures for one account, or 20 from one address, lock sign-in for 15 minutes.
• I forgot the password. The sign-in page's reset link needs a mail server and the install's public URL. When one is missing, the Forgot your password page says which. Until it is fixed, another Admin can set a new password under Settings → Users & roles. If you are the only Admin, reset it from the machine that runs the server. With Docker, in the deploy/ folder: docker compose exec web reqursor-dev admin reset-password <email>.
• I am signed in, then signed out again at once, on plain http://. The session cookie is sent over HTTPS only. Use the HTTPS address. Only on a trusted network without TLS, set REQURSOR_DEV_PUBLIC_URL=http://<address>:8765 in your settings file.

Agent isolation is unavailable

Nothing runs while the sandbox cannot, and the worker says why.

• Bare metal (Linux). Linux must let ordinary users create isolated spaces. On Ubuntu 23.10 and newer a security feature blocks that by default. The installer adds Ubuntu's profile that allows it for the sandbox only, and running the installer again puts it back. Check with sudo -u reqursor bwrap --ro-bind / / true. No output means it works.
• Docker. The runner container must be healthy. In the deploy/ folder, docker compose ps runner shows its state and docker compose logs runner says why it is not.
• Windows. There is no sandbox on Windows. The agent runs without the isolation the Linux installs give it, on a machine you dedicate to it. That is by design, not a fault.

A ticket does not run

It stays Queued, or does not start.

• No worker is running, or the license allows no work. The health check says which.
• Another ticket is running and every slot is taken. A project runs one ticket at a time unless its Tickets at once setting is above 1 and the install can keep runs apart. The Queue page shows the reason when it cannot.
• The worker checks the AI connection before each run. While the provider cannot be reached, the ticket stays queued and the worker tries again later.
• The disk is nearly full. A worker below its free-space floor claims nothing new. Free some space.

Fewer tickets run at once than I set. The Queue page names the reason under Tickets at once: the project uses one working branch for all tickets, the agent cannot be walled off per job, your license allows one worker, the worker is set to run one ticket at a time, or a run policy limits it. Each is a setting.

It went back to Ready, with the reason on the ticket.

• The provider refused the key, a model is not available to it, or the account is out of credit. Fix it under Settings → Claude & models, choose Save and test connection, then start the ticket again. See When the key stops working.
• Someone pressed Stop, or the worker restarted while running it.

It is Paused. A spending cap was reached during the run. The ticket names the cap and the amount it needs, and its work is set aside. Approve budget on the ticket, or raise the cap under Settings → Budgets & guardrails, and start it again. See Budgets.

Start is refused with a cap's name. The project reached a day, month, lifetime or tickets-per-day cap. Raise it, or wait until the window moves on.

It landed in Needs review. The ticket page says why.

• A check stayed red after the fix rounds. Open the check's output on the ticket page. If the check also fails on the base branch, fix that first: Settings → Checks → Run Checks on Base Branch.
• A tool is missing, for example npm: command not found. Install it where the checks run, then choose Retry with hint. See A missing toolchain.
• A criterion had no evidence. The criterion was ambiguous, or the change did not do it. Make the criterion checkable and retry.
• Held for approval. A person approves or rejects the held change.

It failed. The error on the ticket says what stopped the run before the agent could work, for example that the clone was in a state it could not start from. Fix that, then choose Retry with hint.

A ticket's work is in the project's stash list, not in the workspace. A ticket that ran with others worked in a copy of the repository that was removed when it ended. What it left behind, such as a held change or a cancelled run's work, was copied into the project's own clone first. git stash list in the workspace shows it.

The repository

• The clone fails. A private repository needs its token: connect it under Settings → Projects & repository → Connect repository, which also tests it. The token needs read access, and write access to push. The address must be https:// or ssh, without a token in it, and not a local address.
• The token disappeared after you changed the repository address. Moving to another host removes the stored token on purpose. Enter it again.
• An SSH host key changed. The first time the server connects to a host over SSH, it remembers the host's key in the known_hosts file in the data folder. A different key later is refused, in case someone is impersonating the host. If the change is genuine, remove the host's line from that file.
• Nothing is pushed. Pushing is off by default. Turn on Push branches to the repository under Settings → Projects & repository. A push to a protected branch is always refused.
• No pull request. Pull requests need Open a pull request for each shipped ticket, and a token that may create pull requests. On a host other than github.com they also need the GitHub CLI (gh) on the machine. The ticket's run log says which one was missing.

Notifications and imports

• Send test on Settings → Notifications says, per channel, whether it was sent and the error when not.
• "may not be ... (a loopback address)" or "link-local". Webhook, Slack, tracker and mail addresses may not point at the machine itself or at a cloud provider's internal address. Use the service's real public address.
• Slack or webhooks are refused by the license. They need the Team plan or higher, and so does the Linear import. A Jira import needs the Starter plan or higher.
• An import fails. Check the tracker's token under Settings → Integrations, and its address. The error comes back in the Import dialog.

Disk full

When free space drops, the health check warns first (under 1 GiB) and then errors (under 200 MiB), and the worker stops taking new tickets below its floor. Lower the retention days under Settings → System → Retention (run logs and artifacts older than that are deleted between tickets), move the data to a bigger disk, or free space some other way. Backups and clones are never pruned automatically: copy old backups off the machine and delete them.

• License statesStarter, Active, Grace and Expired explained.
• How to get helpThe diagnostics bundle, and what to include in a support request.