Forge stops
A forge task opens, syncs or merges the merge request, and git pushes and fetches the branch. The first column is the text the board and kraft view show ID print. ... stands for text that varies. A row either holds the whole fix or links to an entry below.
Find your reason
| The reason says | What happened | Fix |
|---|---|---|
A forge task, or a git push or fetch, failed and the log shows HTTP 401, Bad credentials, Authentication failed, could not read Username, Permission denied (publickey) or gh auth login | With client: cli or a git-credential token, Kraft holds no forge token, and the forge refused what gh, glab or git sent. | Run gh auth login (glab auth login for GitLab), then kraft item retry ID. See Forge authentication fails. |
A forge task failed, and the stop's facts.cause is forge_auth with an sso_url fact Added in 2.5 | The forge accepted the token but wants it authorised for single sign-on. sso_url is the page that does it. Kraft keeps only a plain https:// address. | Open the address and authorise the token, then run kraft item retry ID. See Forge authentication fails. |
A forge task failed, and the stop's facts.cause is forge_auth with an account fact Added in 2.5 | A client: api account's token was refused or couldn't be read. facts.source says where it is read from. | Replace the token there, restart the server for an env one, then run kraft item retry ID. See Forge authentication fails. |
A forge task failed with HTTP 429, or with HTTP 403 and rate limit in the log, and the item shows rate_limited instead of a stop Added in 2.5 | The forge asked Kraft to wait. Kraft starts the item again when the forge allows it: at the time the forge named, else after a minute. | Nothing. See A forge rate limit. |
The log shows Could not resolve host, Connection timed out or Connection refused on a forge or git call. The stop's facts.cause is forge_unreachable. | The machine the server runs on couldn't reach the forge. | Check that machine's network, DNS and proxy settings, then run kraft item retry ID. |
could not start ... with gh is not installed or not on PATH, glab could not start: ... or git cannot run in <folder>: it does not exist Added in 2.5 | A forge task's CLI never started on the server's machine: it is missing or can't run there, or the item's worktree is gone. | Install gh or glab on that machine, set client: api on the repo's forge account, or put the folder back, then run kraft item retry ID. kraft admin doctor checks that the CLI is on PATH. |
could not start ... with cannot run: backend: auto, but no forge is recorded for this repo | The repo had no GitHub or GitLab origin when you connected it. | See no forge is recorded for this repo. |
forge account NAME: ...'s push URL is not on ORIGIN, the account's address, so Kraft will not send its token there Added in 2.5 | The push URL points off the account's address. | Point pushurl at the account's address or an SSH address, then run kraft item retry ID. See Kraft won't send the token to another address. |
forge account NAME: origin redirects elsewhere; point origin at the new address, then retry Added in 2.5 | A git push or fetch with the account's token met a redirect. Kraft never follows one with the token. | Point origin at the new address, then run kraft item retry ID. |
forge account NAME: git could not verify origin's certificate; set ca_file on the account, or http.sslCAInfo in your global gitconfig, then retry Added in 2.5 | Kraft pins the CA git trusts for a call that sends the token, and none of its sources trusts the origin's certificate. | Set ca_file on the account in forges.yaml, or http.sslCAInfo in your global gitconfig, then run kraft item retry ID. |
repos.yaml does not load (...); fix it, then retry on a git call Added in 2.5 | A client: api account sends a token, and without repos.yaml Kraft can't tell which repo uses it. SSH and local remotes aren't stopped. | Fix repos.yaml, then run kraft item retry ID. |
The account in forges.yaml
| The reason says | What happened | Fix |
|---|---|---|
cannot run: forge account <name> ... with was removed, now says forge: <f>, was <g>, now says client: <api or cli>, was client: <cli or api> or is pinned to <cli>, the repo now says forge: <f> Added in 2.5 | The item keeps the forges.yaml account it first used, and the config now differs: the account is gone, its forge or client changed, or the repo's forge changed. | Run kraft item retry ID. It re-pins the item to the current config. To keep the old one, restore the account or the repo's forge first. |
cannot run: forge_account <name> names no account in forges.yaml Added in 2.5 | The repo names an account the file lacks. A repo not yet pinned never falls back silently to gh or glab; a pinned repo keeps its pin. kraft admin doctor names the account. | Add the account, or fix forge_account in repos.yaml, then run kraft item retry ID. |
cannot run: forge_account <name> says forge: <f>, the repo says forge: <g> Added in 2.5 | The account the repo names is for another forge than the repo's own forge. | Name an account for the repo's forge, or fix forge in repos.yaml, then run kraft item retry ID. |
cannot run: forges.yaml does not load (<reason>); fix it, then retry Added in 2.5 | The server started with a forges.yaml it couldn't read, and the item had not yet pinned this repo. Pinned repos keep running. A repo naming an account says forge_account <name>: ... first. | Fix the file named in the reason, run kraft admin reload, then kraft item retry ID. |
Forge authentication fails
The forge refused the credentials Kraft sent, or couldn't read the token it was to send. The stop's facts.cause is forge_auth, and the card reads Failed with the fix under it. A forge that is only rate limiting Kraft isn't this: see A forge rate limit.
On a client: cli account
Kraft holds no forge token here. It runs gh (GitHub) or glab (GitLab), and git, as the user the server runs as. Nothing in Settings › Repos can supply a token. On the machine the server runs on, sign the CLI in, then run kraft item retry ID:
gh auth login
glab auth login
Use glab for a GitLab repo. If it still fails:
- If git itself can't authenticate, check its credentials:
gh auth setup-git, your SSH key or credential helper.gh auth statusshows who the CLI is signed in as.kraft admin doctorchecks only that the CLI is installed, not that it is signed in. - If the forge asks for single sign-on, authorise the CLI's token for the organisation on the forge's website. When the forge sent the address of that page,
facts.sso_urlcarries it and the card ends its fix with it as a link: open it, authorise, then retry.
On a client: api account
The card reads Forge account NAME could not sign in with its token (SOURCE). It names the account in forges.yaml and where its token is read from, such as env CORP_GL or a file path. The token was refused, or couldn't be read at all. A git push or base fetch that the token can't authenticate stops the same way.
- Replace the token at that source, or paste a new one in Settings > Forge accounts. An
envtoken is read when the server starts, so restart it. - Run
kraft admin forge test NAMEto see the token accepted. - Run
kraft item retry ID.
A git call with the token that meets a redirect stops the item, because Kraft never follows a redirect with the token: point origin at the new address, then retry. GitHub answers a private repo it won't show a bad token with "repository not found", so when Kraft sent the token, that counts as a token problem. On an API account the card names the account whose token needs single sign-on.
A forge rate limit
Added in 2.5
The forge answered a call with HTTP 429, or with an HTTP 403 that says it is a rate limit: GitHub's X-RateLimit-Remaining: 0, a Retry-After, or a message naming a rate limit, which is all GitHub's secondary limit may send.
Nothing to do but wait. The forge hasn't refused your credentials, so the item doesn't stop for you: its status is rate_limited, a rate_limit_hit event records when to come back, and Kraft starts the item again at that time. The time is the forge's Retry-After when it sent one, else when GitHub's spent quota resets (X-RateLimit-Reset), else a minute.
If the limit keeps coming back, the account the server's gh or glab is signed in as, or on a client: api account its token, is spending its quota elsewhere. Sign in with another account, or give it a token with a higher limit. A 403 with none of these signs is still Forge authentication fails.
no forge is recorded for this repo
The repo had no GitHub or GitLab origin when you connected it, so Kraft doesn't know which forge CLI to run.
- Set
forge: githuborforge: gitlabon the repo in Settings › Repos, then Review & publish (or set it inrepos.yaml). - Run
kraft item retry ID.
Kraft won't send the token to another address
Added in 2.5
The push URL isn't on the origin of the account's web_url, so Kraft won't send its token there. Point pushurl at the account's address, or at an SSH address, then run kraft item retry ID. A fetch isn't refused, but carries no token off the account's address.
Caps, budgets and waits
Fix a work item that stopped on a dollar, token or time cap, and one that waits on CI, a review, a gate or a machine and nothing moves.
Worktree and git stops
Fix a work item that stopped on a rebase conflict, a worktree git won't rebase or commit in, a branch someone else pushed to, or a branch origin lost.