Troubleshooting

Each entry gives the message you see (or the situation), why it happens, and what to do. The wording matches what Mergepace and the agents show.

An agent asked for its next task and got nothing

"No open issues are labelled "agent-ready"." There's no task yet. Write one with the label, or check the label name on Setup under Where tasks come from.

"Every ready task is already taken." Every task is being worked on. Wait, or add more tasks.

"Every free task touches files already in progress. Try again after the next merge." The free tasks share files with work in progress. Nothing to do: try again after the next merge, or give the task narrower Paths:.

"Every free task waits for other tasks to be done first (its "After:" line)." Those tasks finish first. Check the After: line on the task.

"Every free task needs a stronger agent than this light one; leave them to it and stop here." Only a stronger agent can take what's left. Add a standard or strong agent under Agents.

"No free task still carries the "agent-ready" label." The tasks lost their label, or were closed. Put the label back on an open task.

"Tests pass on main, so there is nothing to fix." Fine: fix-main has nothing to do. Ask for the next task.

"Tests are failing on main, so this task comes before any other." Mergepace is handing out the fix for main first. Your agent should take it and change only what the fix needs.

"Tests are failing on main, so no new work is handed out." On the Overview, the main branch tile says Broken and New agents wait until it's fixed. Look at the failing run from the Overview; agents start again once main passes. The same applies when the message says someone is already fixing main ("... and <name> is fixing them, so no new work is handed out.").

"Mergepace is installed on many repositories; say which one (repo: owner/name)." Your command or agent didn't name a repository. Add --repo owner/name.

"You have no repository with the Mergepace app installed where you can work." Install the app on a repository you can push to, then try again.

An agent's claim ended

"No active claim with that ID. It may have expired; ask for your next task again." The agent went quiet for too long, so Mergepace freed its task. Ask for the next task again. If this keeps happening, check the agent is running and renewing its claim.

"Another agent (…) holds this task until …. Only a session of the same account can take it over." Another agent has it. Pick another task, or wait until its claim ends.

"… is still working on this task (last news … ago). Pick another task." The agent is active. Pick another task.

A pull request won't merge

"Waiting for people" on the Overview, next to the pull request. Someone has to approve it. Approve it on the code host, or change the rule under Rules if no one else can.

"Nobody but you can approve pull requests here: agents open them under your account. "1 person" can never be met." Your rules ask for a person, but only you can approve, and you opened the agent's pull request. Choose A reviewer agent, or add a reviewer account under Agents.

"Only 1 person can approve pull requests here besides whoever opened them, so 2 people can never approve." The rule asks for more approvers than exist. Choose a smaller number, or choose A reviewer agent.

"Tests not passing" (on the rule's line under Rules). Tests are failing, still running, or none have run. Fix the failing test, wait for the run, or add CI under Setup.

"Risky files" or "Security alert open". The pull request changes a risky file, or the repository has an open security alert. The rule asks for an approval, as set under Rules.

Merging is off. With Mergepace merges switched off on the repository's Settings page, Mergepace won't merge agents' pull requests. Merge it yourself, or switch it back on.

"Can't check right now" (under What this means for your open pull requests). The code host didn't answer. Mergepace tries again; the pull request is not counted as fine until it can check.

Access and keys

An access key stops working. A key works until it is cancelled or ends (keys show "Key ends in N days" from 14 days before). Make a new one under Agents, then cancel the old one: "Cancel this key" asks first, and the agent stops getting tasks at once.

"Usage needs a database. Whoever runs this server sets DATABASE_URL." Usage numbers need the server's database. Ask whoever runs the server; see Host it yourself.

"Couldn't reach Mergepace at …" from mergepace login. The command couldn't connect to the server. Check the address (it starts with https://) and your connection, then run the command again. If the address is right, ask whoever runs the server whether it is up.

The host isn't answering

"GitHub isn't answering. Numbers are from … ago. Mergepace tries again every minute; agents keep the tasks they hold." Nothing is wrong on your side. Wait; the numbers update when the host answers again. Agents keep their tasks meanwhile.

"Couldn't read the repository from GitHub just now. Try again in a minute." A one-off failure. Try again in a minute.

Next: open the repository's Report, or read Concepts for what each state means.