Troubleshooting

This page maps symptoms to causes and fixes. Text in quotation marks is the app's own wording.

Providers and models

A provider shows “not set up”

The amber “not set up” badge in Settings → Providers means Motriz has no working credential or CLI for that provider. Expand the card: the detail line names what is missing and the hint tells you how to fix it.

1. For Claude Code, install the CLI and run claude auth login, or save the binary's absolute path in the “Claude Code CLI path” field.
2. For Codex, “Codex authentication not found” means the CLI is present but you are not signed in — the hint says it plainly: “Run codex login to sign in.”
3. For API providers, save a valid key (Azure OpenAI also needs its “Endpoint URL”). Each hint names where to create the key.

A warning pill in the composer carries the same diagnosis: “This provider isn't configured. Set it up in Settings → Providers, or pick a different model.” See providers and models for per-provider detail.

Models are missing from the picker

The picker lists models from connected providers only — unconfigured providers are hidden entirely, and ChatGPT lists no models until you sign in. With nothing connected it says: “No providers connected yet — set one up in Settings → Providers.” You can also type any model id; the picker offers a “Use typed model” group.

ChatGPT sign-in never finishes

“Sign in with ChatGPT” opens your default browser and waits on a local callback at port 1455. If it stays on “Waiting for browser…”, finish the authorization, or press “Cancel” and retry. If another sign-in holds the port, Motriz says so: “port 1455 is in use — close any other Codex/ChatGPT sign-in and retry”.

The task queue

The queue paused after a task failed or was stopped

Any failed or cancelled task pauses the whole queue; later stages stay queued, untouched. That is the design — the queue never runs past a failure it hasn't shown you. Open the failed item's record from Build and read the failure record, fix the task or use “Reset to backlog”, then press “Resume queue”. See Build, tasks, and review.

If a task shows “The app stopped before this task finished. Review its thread before retrying.”, Motriz quit mid-run; the task is marked failed on the next launch and the queue pauses.

“Parallel work is ready to integrate”

This banner is not an error. Parallel stages run in isolated worktrees and Motriz never merges branches for you, so when one finishes with dependent work still queued, the queue pauses and asks: “Open each completed task thread, integrate its isolated branch into the project checkout, then resume the queue.” The note stamped on each completed task is a warning, not a failure. Open each thread, review its Changes, merge its branch, pull the default branch in the project checkout, then press “Resume queue” — that is your confirmation the branches are in.

Queued tasks wait but nothing starts

The queue claims work only while the repository is idle — if another agent run is active in the same checkout, tasks wait instead of failing. Starting a run manually in a busy repository is refused: “Another agent is already running in this repository (thread {id}). Stop it before starting this run.”

Git and GitHub

Git actions are disabled

The branch pill's tooltip reads “Git actions are paused while a run is in progress”. Motriz refuses to change Git state under an agent that may still be writing. Stop the runs, then retry.

Push or PR calls fail with an auth error

“GitHub authentication failed” means Motriz could not act with your GitHub identity. There is no in-app GitHub login: Motriz reuses your environment — first gh auth token, then git credential fill. Run gh auth login in a terminal, then retry; whatever works in your terminal works here. Two more common blocks: PR controls support GitHub.com remotes only (“This Git remote is not a supported GitHub.com remote, so PR controls are disabled.”), and pushing needs an origin remote and a checked-out branch (“Cannot push from a detached HEAD”).

“Suggest” fails for commit messages and PR text

The “Suggest” buttons in the Git dialog generate text on-device with Apple Intelligence — there is no cloud fallback. When the device can't run it, the message is: “Apple Intelligence suggestions require macOS 26, supported Apple silicon, and Apple Intelligence enabled. The fields remain manually editable.” As it says, the fields still work — write the text yourself.

Composer, dictation, and images

Thread names stay “New work”

Auto-naming also runs on-device through Apple Intelligence, with no cloud fallback — when it is unavailable, threads keep the default title “New work”. Click the title in the conversation header to rename; a manual title is never overwritten.

Dictation won't start, stops early, or errors

1. If pressing the mic opens Settings → Voice, no speech model is installed. Download one — “Base (recommended)” is the smallest. Transcription runs entirely on this Mac; see privacy and safety.
2. Recordings cap at 120 seconds of audio; longer dictation silently stops accumulating.
3. On a permission error, follow the message: “Check microphone access in System Settings → Privacy & Security → Microphone.”
4. Esc cancels a recording and discards the audio — if your words vanished, that is why.

Images are refused or dropped

Image input is gated per model. Pasting with a text-only model is refused: “Image pasting doesn't work with {model} — it can't see images. Quoted text and other files still work.” Images staged before a model switch are dropped at send: “Attached images will be dropped — {model} can't see images.” Pick a model showing the “Understands images” icon in the picker. Grok and Cerebras accept PNG and JPEG only.

Repositories

The scan doesn't find your repository

The product entry scan starts from your home folder (the roots are listed under Settings → About as “Repo roots”) and descends at most 6 directory levels. It deliberately skips dependency and build folders, dot-directories, macOS bundles, heavy home folders, and VM or container mounts (OrbStack, Parallels, Docker, network filesystems). Inside a monorepo, only the outer repository surfaces.

1. Press “Rescan” — results are cached for 20 seconds, so a fresh clone may need it.
2. If the repository is deep, on a skipped mount, or outside your home folder, use “Choose a folder…” and pick it directly. The folder doesn't need a GitHub remote — or even Git.
3. Power users can widen the scan with the MOTRIZ_REPO_ROOTS and MOTRIZ_REPO_SCAN_DEPTH environment variables.

Updates

The update pill never appears

Update checks run only from an installed Motriz.app bundle, and the release manifest is consulted at most once per hour (failed checks are silent). A fresh release can take up to an hour to surface, and only a strictly newer build is offered.

The update is blocked or fails

With agents running, the pill reads “Update ready (v{version}) — stop active runs first” and the install is refused with “Stop all active agents before installing an update”. Stop the runs and click again. A checksum failure right after a release usually means the files are still propagating; try again in a few minutes. Motriz never installs an archive that fails the published SHA-256 checksum or the code-signature check.

Version, paths, and verbose logs

Settings → About shows the app version, the repository scan roots, and the database path (the default data folder is ~/Library/Application Support/Motriz/). When reporting a problem, include the version and the exact visible message. For deeper provider diagnostics, launch Motriz from a terminal with MOTRIZ_DEBUG=1 for verbose provider logs. Search and connection testing live in integrations and web search; run behavior is explained in work and runs and flows.