Factory troubleshooting

Start with these three commands. Together they cover most problems:

archdev repo status          # login, model access, repo wiring, hooks
archdev jobs runner status   # is the daemon running?
archdev check                # is archdev.json valid?

Factory won't start

Message	Cause	Fix
`Factory mode needs an initialized repository.`	No `archdev.json` at the repo root	`archdev jobs setup`
`Factory cannot start because the local ArchDev daemon is not installed.`	Daemon missing (non-interactive shell)	`archdev jobs runner install`, then `archdev jobs setup`
`Factory cannot start because the committed ArchDev pipeline configuration is invalid: …`	`pipeline_bindings` in the committed `archdev.json` names a pipeline that is missing or invalid	Fix the pipeline or the binding, run `archdev check`, commit
`Factory tasks will not open pull requests…` (warning)	Custom pipeline with no publish step and `publish.auto` off	Add `"publish": {"auto": true}` and commit
Sync refused: dirty files, detached HEAD, merge commits, branch not tracking `origin/main`, branch checked out elsewhere	Checkout is behind `origin/main` and can't be rebased safely	Commit or stash, `git switch main`, or start with `--no-rebase`
`Factory project lock is already held for <path>.`	Another Factory is running for this repository	`archdev agents factory status`, then `archdev agents factory stop`
`Not authenticated. Run archdev auth login first.`	Signed out	`archdev auth login`
`…Run claude login first, or set factory.worker_harness to "archdev"`	Claude Code worker harness without `tmux`, `claude` or a Claude login	Install tmux and Claude Code, then run `claude login`

Models

Symptom	Fix
`<provider> is not authenticated. Run archdev provider login <p>`	`archdev settings provider login <openai\|xai>`; for Claude, `… login claude --api-key <key>`
Browser login never completes over SSH	Add `--device-code`. The browser flow redirects to `localhost:1455` on the machine running the CLI.
`No configured agent model is available` from `agents setup`	Connect at least one provider, then check the IDs with `archdev settings provider models <provider>`
Workers are slow or idle and the logs mention usage limits	`archdev settings provider usage` shows which accounts are near their limit. Add another account, or add a fallback to `factory.worker_model`.
`archdev settings provider list` shows `N accounts benched (usage limit), next back <time>`	Wait for the reset, or run `archdev settings provider accounts <openai\|xai> reset` once you know the limit has cleared
A model keeps being skipped after you fixed its login	`archdev agents factory reset-circuits`
ArchDev Model Router refuses with `insufficient_credits`	Add credit; see Pricing and billing

Daemon

Symptom	Fix
`jobs runner status` shows `stopped`	`archdev jobs runner start`
`jobs runner status` shows `not-installed`	`archdev jobs runner install`
Status is wrong after an upgrade or move	`archdev jobs runner doctor`. If it reports `repair available`, run `archdev jobs runner doctor --repair`.
Jobs fail with `command not found` (git, gh, node, your test tools)	The service saved an older `PATH`. Run `archdev jobs runner install` again from a shell that has the right `PATH`.
`ArchDev repo name "<x>" is already registered`	`archdev jobs setup --name <unique-name>`
`Git remote "archdev" already points to …`	Another setup owns that remote. Remove it with `git remote remove archdev`, then run `archdev jobs setup` again.

Logs: ~/.archdev/logs/daemon.log and daemon.error.log. Job details: archdev jobs list, archdev jobs show <id>, archdev jobs logs <id>.

Tasks

Symptom	Fix
Ready Tasks but idle workers	In `--dispatch manual`, release them with d in the Tasks tab. Otherwise check the Task's readiness in the Tasks tab or with `archdev tasks ready --explain`.
Task shows `ownerless`	It has no owner. Ask the overseer to dispatch it, which assigns it to you.
Tasks saved with `review start --team` never run	`--team` saves outside your organization's tasks, where the Factory doesn't look
Task never claimed, but other Tasks are	It belongs to another repository. Create plans from the checkout the Factory runs in, or pass `--repository owner/repo` to `tasks review start`.
`Task X needs a dependency reason for Y`	Add `"dependency_reasons": {"Y": "…"}` to Task X
`Import requires a task graph with action set to preview`	Set `"action": "preview"` in the plan file
Plan save blocked by `pre-merge-unsatisfiable`	Move production, rollout or sign-off work into a `"kind": "human"` or `"kind": "post_deploy"` Task
Duplicate Tasks after a second review	The review receipt for that plan was lost. Close the duplicates. Next time, keep the receipt file or pass the same `--state-file`.
A paused Task flips back to paused after you reopen it	The overseer pauses it again because the question is unanswered. Answer it with `archdev tasks answer`.

Pull requests

Symptom	Fix
Task finished but no PR was opened	`archdev jobs list` shows the `branch_update` job for that Task; read it with `archdev jobs logs <id>`. Check that `gh auth status` works in the daemon's environment.
Task failed with `The repository rejected the catch-up commit 4 times; checkout retained`	The pre-commit hook kept failing. The worker gets the hook output and 3 correction rounds, then the Task fails and its worktree is kept. Fix the failure (often one already on `main`), then restart the Task with r in the Tasks tab.
PR stuck in Needs you after remediation gave up	Rearm (r), rearm with a hint (w), pause (p) or close (c)
Need to resubmit a finished branch	Stop the Factory, then `archdev agents work resubmit <id>`

Still stuck? Contact us with your OS, archdev --version and the error text. Never include tokens or credentials.