Troubleshooting

A provider says “not set up”

1. Open Settings → Providers and expand the provider.
2. Read the status detail and configuration hint.
3. For Claude Code, confirm Node.js 22+ and the Claude CLI are installed, then run claude auth login.
4. For Codex, confirm the Codex CLI is installed, then run codex login.
5. If Motriz cannot auto-detect a CLI, save its absolute binary path.
6. For API providers, enter a valid key and any required endpoint.

You can also choose another configured model from the composer.

ChatGPT sign-in does not finish

• Complete the browser authorization and return to Motriz.
• If the app remains on Waiting for browser, choose Cancel and retry.
• The local callback uses port 1455. Close another ChatGPT or Codex sign-in process that is using that port.
• Use Sign out, then sign in again if the stored account is no longer valid.

A flow cannot run

Every step and fan-out branch must have a model, and every provider used by the flow must be configured. Open Flows, inspect each step, then either connect the missing provider or replace the model.

No repositories are discovered

• Open Settings → About and verify the Repo roots.
• Return to Add project and rescan.
• Paste the folder path directly. It only needs to exist and be a directory.
• Remember that virtual-machine and container mounts are intentionally skipped.

An attachment fails before sending

Confirm that the file is non-empty, supported, no larger than 10 MB, and that the message contains no more than 10 attachments. Common source/text formats, JSON, CSV, logs, PNG, JPEG, GIF, WebP, and PDF are supported.

Dictation opens Voice settings

No voice model is installed or selected. Download a model in Settings → Voice, wait for the download to finish, and select it. Then return to the composer and retry.

Search returns no results

1. Open Settings → Web search.
2. Enable at least one engine.
3. If Brave Search API is enabled, save a valid key.
4. Use the test box. If one scraper fails, enable another engine and test again.
5. Check SafeSearch and region if relevant results are being filtered.

An integration is expired or unavailable

• Stop active agent runs; integration changes are disabled while they run.
• Choose Test connection for a connected workspace.
• Choose Reconnect when authorization expired or was revoked.
• Choose Try again for a temporary provider failure.
• Disconnect and reconnect if the wrong workspace or account was authorized.

A run appears stuck

• Read the current activity and elapsed time; long tool operations can continue without a new chat message.
• Open the run timeline for provider and nested activity state.
• Stop the run if it is not making useful progress.
• Check provider login, network access, and the selected model, then continue in the same thread.

Git actions are disabled

Stop active runs in the repository. Git mutations are intentionally paused while an agent may still be changing the same checkout.

Pull or cleanup is blocked

A dirty worktree blocks fast-forward pull, default-branch checkout, and post-merge cleanup. Review the changes, then commit them or deliberately discard them outside Motriz. Do not remove unknown work just to make the control available.

GitHub pull request controls are unavailable

• Confirm the repository has an origin remote.
• PR controls currently support GitHub.com remotes.
• Create or check out a feature branch; Motriz will not open a PR from the default branch or detached HEAD.
• Confirm your local GitHub authentication can access the repository.

A parallel stage will not continue

The queue pauses after parallel work so you can integrate isolated branches. Open every completed task thread, combine the desired branches into the project checkout, resolve conflicts, validate the combined state, then resume the queue.

An update fails verification

Stop all runs and retry after a few minutes. A checksum mismatch can occur while a newly published release is still propagating. Motriz refuses to install an archive that does not match the published SHA-256 checksum or expected signing identity.

Find version and local paths

Open Settings → About to see the app version, repository roots, database path, and local runtime URL. Include the version and exact visible error when reporting a reproducible problem.