Fix a custom agent whose refresh failed
Jaah re-checks a custom agent's branch or tag after each push and pins its newest commit. When that check fails, the agent is marked Last refresh failed and Jaah keeps running the last commit it pinned, so your newest change is not running yet. An agent marked Never fetched failed its very first check and runs nothing at all. An agent built on SDK v1 is marked Unsupported instead, its row says Re-register on SDK v2, and hovering its name reads Built on SDK v1. This guide reads why, fixes it and checks the result. What a refresh is, and the other marks an agent can carry, is in How agents work.
Fixing an agent needs the permission to edit agents; without it, its page says You can view this agent but not edit it.
-
In the sidebar, select Settings, then Agents under Customize, then the Custom agents tab.
-
Find the agent whose mark is !. Hover the mark to read Last refresh failed or Unsupported, or hover the agent's name for its facts, its source and the reason. An agent whose name reads Unsupported and Re-register on SDK v2 is built on SDK v1 (step 4); hover Unsupported for why.

-
Select the agent's name. Its page opens with a warning that starts Last refresh failed: and gives the reason in full. On an SDK v1 agent the warning reads Built on SDK v1. Re-register on SDK v2.
-
Fix what the reason names:
- A problem in the manifest or the folder, such as a missing field, or a script that imports the SDK without carrying it: fix it in the repository and push. Every rule is in the Agent SDK reference.
- A branch, tag or folder that no longer exists: change Ref or Sub-path on the Agent tab and select Save, as in Change or remove a custom agent.
- Jaah could not reach the repository: check that your own Git connection under Settings › Personal › Git still reaches it.
- Built on SDK v1 (the agent is marked Unsupported): move its code to SDK v2 and refresh it, as in Move a custom agent to SDK v2.
-
Select More, then Refresh, to check the repository again now rather than waiting for the next check. A note on the page confirms it, or names what still fails.
-
Read the mark beside the agent's name. Active means the warning is gone and Jaah has pinned the new commit: the Facts line under Details names it. Still Last refresh failed: read the new reason and repeat from step 4.
Tasks already set to an agent that has never been fetched, or that is SDK v1, fail to start with the reason until it is fixed; tasks on an agent whose later refresh failed keep running its last pinned commit.
Related
- How agents work — what a refresh pins and every mark on the Custom agents tab.
- Change or remove a custom agent — change the ref or folder, disable or delete an agent.
- Agent SDK reference — the manifest's fields and the failure codes a run can end with.