openfabriq
Reference

Troubleshooting

Find out what happened, and fix the usual problems.

Start with openfabriq doctor in your repository. It installs and runs nothing.

See what is happening

WhereWhat it shows
openfabriq doctorWhat this machine lacks, the sites the factory calls that network does not reach, and the sites its last runs were refused
The studio's boardWhat waits, works, needs you, is done; the navigation counts the runs that need someone
openfabriq statusThe same, in a terminal
GitHubEvery result: a comment, a label, a pull request
/openfabriq:diagnose in Claude CodeWhy something happened or not, and what to change, read from the runs and the applied factory. Needs the plugin

Read a failed run

Open the run in the studio: Summary (what started it, what the agent reported), Logs (the conversation, with the commands and checks the engine ran), Outputs (each proposal, and why it was applied or refused), Files changed (each diff). Or ask the chat "Why did the last run fail?": it reads the runs and the factory. Then find the symptom below.

The factory does not load or start

SymptomCauseFix
openfabriq needs a few things on this machine firstClaude Code, the GitHub CLI or your git identity is missing or logged out (checked once, on the first init, plan, apply, start or run)Run the commands it lists. After a later logout, the tool's own error shows: claude auth login or gh auth login
openfabriq init … needs an interactive terminal and the claude commandRun from a script, or claude is not on your PATHUse a terminal, or copy a template: openfabriq init --example <name>
start says no project yetNo factory applied on this machineopenfabriq apply in your repository, or openfabriq start there, which applies first
apply warns You are on branch … or uncommitted changesYou apply a factory that is not mergedCommit, push and merge openfabriq/, then apply from the default branch
start says the relay is not connectedThe factory listens to Slack, Linear, Sentry or a webhookopenfabriq connect relay, then restart start
start says … not set on this machineA secret (of secrets or an MCP server) has no value hereopenfabriq secret set <NAME>; the next run uses it
start says 127.0.0.1:4310 is takenAnother program, most often another openfabriq start, uses the studio's portStop it (Ctrl-C in its terminal), or pass another --port
start says another "openfabriq start" (process …) runs the projects of …An engine already runs on this engine folder; two would break each other's runsStop it, or give this one its own folder with OPENFABRIQ_HOME
The studio says Open the studio from the address that "openfabriq start" printedEach start draws a new token, locking out tabs opened beforeOpen the last address start printed, with ?token=
The studio says The factory applied to … does not load, then the file and its first errorAn update changed the format (for example, slack, linear and sentry moved under integrations)openfabriq validate, fix what it lists, openfabriq apply

Runs

SymptomCauseFix
Adding a label starts nothingAdded by someone outside maintainers, factory not applied, or start not runningCheck maintainers; openfabriq plan should report nothing to change; check the terminal of start
An agent's comment started nothingThe engine's comments start nothing, so an agent cannot restart itselfChain steps with a label
A run is skippedThe daily limit (usd_per_day) was reached, or the event matched nothing that could runRead the reason in the run. It never comes back on its own: raise the limit or wait, then openfabriq run
The pull request was refused, and the issue has needs-humanA check still failed at the end, or the agent changed .github/workflows/Read Checks and commands in the run; fix the change by hand, or improve the agent's procedure
An output was refusedThe automation's can does not allow itAdd it to can if it should
Runs are billed to an API key, not the subscriptionANTHROPIC_API_KEY is set in the engine's environment, and winsstart says which credential it uses; unset the variable and restart
Two pull requests for one issueTwo engines watch the repositoryRun the factory on one machine only
A nightly schedule ran in the morningThe machine slept; the missed run was caught up onceWake it beforehand: sudo pmset repeat wakeorpoweron MTWRFSU 01:55:00

Network

SymptomCauseFix
A command or check ends with openfabriq: the network refused …; web says … is not in this agent's network; the shell shows deny network-outbound … (host is not on the allow list)The site is not in networkAdd it to network in factory.yaml, or in agent.md for one agent whose job needs it; apply
curl says CONNECT tunnel failed, response 403, or Node says fetch failedThe sandbox's proxy refused the siteopenfabriq doctor lists the sites the last runs were refused
setup fails while a tool downloads its own files, such as Playwright's browserssetup reaches only the package registries and networkInstall the tool on the machine, or add its site to network
A listed site is refused: the shell says resolved to a loopback address, or a command or check ends with openfabriq: the network refused …, a name that points to this machine, even listed: reach it as localhost.The name points to this machine (a DDEV site, say)Use localhost and its port

Sandbox and Linux

SymptomCauseFix
setup fails in the run but works in my terminalEngine commands run in a sandbox: no writes to git or the home folder, no secretsInstall into the project's folders; on Linux, install ripgrep, bubblewrap and socat
EROFS, EPERM or ENOENT on mkdir '~/.gradle' (a folder of the home folder)Sandboxes never write the home folder; only ~/.config is redirected (XDG_CONFIG_HOME), and for engine commands ~/.cache, to the project's cachePoint the tool's variable at a checkout folder in env (GRADLE_USER_HOME, CARGO_HOME…), or turn the feature off (ASTRO_TELEMETRY_DISABLED, NEXT_TELEMETRY_DISABLED)
On Linux, every run with shell failsThe agent sandbox requires bubblewrap and socatsudo apt install bubblewrap socat
On Linux, a server or a browser the agent started is gone at its next commandEach shell command has its own sandbox, which stops what it startedStart, use and stop the app in one command, as the browser-evidence skill's script does
Runs fail with a bwrap error in DockerThe sandbox cannot create its namespaces in the containerKeep the security_opt of docker-compose.yml; see what the sandbox costs the container

Slack, relay and webhooks

SymptomCauseFix
Slack mentions get no answerBot not in the channel, start not restarted after connect slack, or relay not connected/invite @openfabriq, restart start, check the relay
A Linear label starts nothingThe openfabriq app does not send Issues webhooks, or the issue is another team'sTick Issues in the Linear app's webhooks; check integrations.linear.team
A new Sentry issue starts nothingconnect sentry ran before the relay existed, or the token cannot list issuesRerun openfabriq connect sentry; start prints the relay's error for a failed search
connect relay reports no workers.dev addressYour Cloudflare account has no subdomain yetOpen Workers & Pages in the dashboard once, then retry
A webhook answers 401The relay does not know it (no connect webhook), or the sender's secret differsRerun openfabriq connect webhook <name>, update the sender

Get help

Still stuck? Open an issue on GitHub.

On this page