Software Factory troubleshooting
The most common reasons a factory run does not start, waits or fails, what belai rc's setup checks mean, and how to fix each one.
Start here when a run does not start, sits waiting, or fails. The API refuses a request with a code in issues[].code; Error codes lists every one. A run that waits or fails says why on the run page, on the card and in the event stream.
Setting up
| Symptom or message | Cause | Fix |
|---|---|---|
403 with "code": "plan_locked": The Software Factory needs Pro, or a Pix Sandbox on Community. |
A Community organisation with no active Pix Sandbox | Move to Pro, or buy a sandbox, which stays open on Community. See Who can use it. |
A trigger never fires, and its webhook row shows needs_permission or needs_webhook_move |
The GitHub App lacks the permission the event needs, or its webhook still points at an old URL | Grant the named permission (for example Actions: read for workflow_run), or update the App’s webhook URL. See Managed scope. |
Connecting a forge fails with <host> answered as Gitea, not Forgejo, the token was refused: ... or the token cannot list ...'s repositories |
The wrong forge card, or a bot token without the scopes or repository access the factory needs | Use the card for the forge the host reports. Create the token with the listed scopes. See Forge connections. |
A run did not start
| Symptom or message | Cause | Fix |
|---|---|---|
A default workflow ignores a repository, with a trigger.skipped event |
The repository’s effective autonomy is below what that default needs: pr-review needs suggest, the fix and sweep defaults draft_pr |
Raise the repository’s autonomy, within autonomy.max. See Autonomy levels. |
| A workflow of your own never runs on a repository, but the defaults do | The repository is under org defaults: it has no settings row, and only default workflows start work on it | Open it on the Repos page and save its settings panel. See A repository’s own settings. |
scope_unmanaged_repo: <repo> is not a managed repository. Manage it in Settings first. or <repo> is not in this workflow's scope |
A manual start named a repository outside the managed orgs or outside scope.repos |
Switch Managed on for its organisation, or add it to the workflow’s scope and publish. See Graph limits. |
Start or retry refused with factory_stopped; other actions with bad_state |
The factory is stopped, or the run is not in a state that allows the action | Resume the factory from Settings. See Pause, stop and resume and the action table in Runs and steps. |
Runs sit as held |
A pause, stop, maintenance window or schedule blackout. Blackouts use schedules.tz, which defaults to UTC. |
Wait for the window to close, or resume. Set schedules.tz to your own zone. See Holds and blackouts. |
A run waits or fails
| Symptom or message | Cause | Fix |
|---|---|---|
A crew step is waiting with host_offline, stopped_by_user or repo_not_cloned |
No host can take the step yet. A stopped sandbox is never woken. | Start belai rc on the machine, or start the sandbox. Every reason is in Waiting for a machine. |
The run fails with no_host_timeout:<node> or no_host:<node> |
The step waited longer than autonomy.no_host_ttl_hours (6 by default), or was pinned with runOnFallback: none and had no host |
Connect a host that has the repository, or change the step’s runOn. Check with GET /v1/factory/hosts/eligibility. |
Your own machine runs belai rc, but the factory never uses it |
belai rc registered the host under whoever is signed in to the Vulnesis CLI. Only the run’s principal’s hosts are candidates. |
Sign in as the workflow’s author, or the member who made the organisation managed. See Hosts and placement. |
A run is paused and nobody paused it |
A budget’s pause_run action reached its limit |
Resume it, or raise the budget. See Budgets. |
belai rc will not start
belai rc prints a check for each requirement and stops with Remote control is not running. Fix the ✗ lines above and run `belai rc` again. See Remote control.
| Message | Cause | Fix |
|---|---|---|
the Vulnesis CLI is logged in with an API token, which the website does not accept for remote control |
Remote control needs a browser login | Run vulnetix auth login without --token, and unset VULNESIS_API_TOKEN. See CLI authentication troubleshooting. |
session sync is off, so the website cannot see or start sessions |
sync.enabled is off |
Run /sync on in Belai, or set "sync": {"enabled": true} in ~/.vulnetix/belai/settings.json |
no directory to offer: nothing is trusted yet and no --dir was given |
No trusted project and no --dir |
Run belai rc --dir <path>, or open belai in the project once and trust it |
Still stuck
Note the run’s display key (such as run_3f9a2c1e) and its failure reason from the run page, and download its evidence zip if it has one. For a host, collect the output of belai rc --status, the check lines belai rc printed, and ~/.vulnetix/belai/rc/rc.log if it runs with --detach. For a sign-in problem, add vulnetix auth status and vulnetix version.