Skip to guide

Troubleshooting

If onemind is not working as expected, run onemind version first to confirm the installation, then find the matching entry below.

onemind Is Not Found

  • macOS/Linux: confirm ~/.local/bin is on PATH and open a new terminal.
  • Run the installer again to repair the binary and service registration.

Browser Authorization Expired Or Was Denied

Press Escape, select Sign in again, and approve the new request in the browser. A denied or expired request cannot be reused.

onemind Cannot Reach The Server

Run onemind session status to see the API URL in use. To change it, run onemind server https://your-server from a terminal. Only https:// URLs are accepted; plain http:// is allowed only for local loopback addresses. After changing the server, the previous credential is removed; run onemind and select Sign in for the new server.

Sync Says No Local Project Is Connected

onemind sync prints one of the following messages when no active binding exists:

  • "Sync has not started. Detect an AI tool with 'onemind project TOOL'" — run onemind project TOOL /path/to/repo to detect the repository, then complete Sync Setup to bind it to an ordinary Project, then run onemind sync again.
  • "Sync setup is saved, but local access is blocked" — the path exists in Sync Setup but the process cannot read or write the directory. Grant the required filesystem permissions, then run onemind sync again.
  • "Sync setup is saved, but the local target is unavailable" — the bound path does not exist or the AI tool is not running. Start or repair the AI tool, restore the path if needed, then run onemind sync again.
  • "Select this device, target, and Project at …" — the device or target has not been enabled in Sync Setup. Open Sync Setup, enable Sync for this device and target, then run onemind sync again.

Sync Rejects AGENTS.md

onemind stops when its managed markers are malformed or ambiguous. Restore a valid pair of markers, run onemind mind restore pre-onemind --yes to return to the pre-onemind agent prompts, or copy .one-mind/AGENTS.md.backup over the live instruction file manually; preserve all content outside the managed block when editing by hand.

Undo The First Mind Sync

After the first Mind sync, recovery means returning to the status before onemind took over—the previous local agent prompts in the instruction file—not restoring a Matrix Mind version.

onemind mind backups --path /path/to/destination
onemind mind restore pre-onemind --path /path/to/destination --file AGENTS.md --yes

For global tool homes, pass that tool root as --path (for example ~/.codex with --file AGENTS.md, or ~/.claude with --file CLAUDE.md). Modifying ~/.codex or ~/.claude directly is a last-resort recovery step; always start from the backup copy and preserve any content outside the managed block.

The Background Service Is Not Running

Run onemind service status. If it fails, try onemind service install, then check the status again. On Linux, ensure the user systemd session and Secret Service/keyring are available.

Secure Credential Storage Is Unavailable

onemind does not fall back to plaintext credentials. Start or unlock the operating system's credential service, then reopen the CLI and sign in again.

Session Not Found In Secure Storage

If the CLI reports "OneMind session not found in secure storage", the stored credential has been removed or was never written. Run onemind and select Sign in to create a new session.

OneMind Version Regression Refused

If sync stops with "refusing OneMind version regression from vN to vN", the cloud package contains a managed block written by an older CLI version than the one that currently owns the instruction file. This normally means the CLI was downgraded after a sync ran. Reinstall the current release using the official installer from CLI quick start, then run onemind sync again.

Propose Failures

onemind propose may fail with one of the following messages:

  • "choose an exact Project target in OneMind before proposing" — no Project binding is active for the current directory. Run onemind project TOOL /path/to/repo and complete Sync Setup before proposing.
  • "proposal is queued locally; exact Project upload is not active" — the proposal was saved locally but upload is blocked because the Project binding is not fully activated. Complete Sync Setup, then run onemind sync to flush the queued proposal.

A Permission Request In The Matrix Panel Shows As Expired

Tool requests expire if nobody answers in time. If a task's detail panel shows Expired or Cancelled for a request, the tool treated it as declined, and its run may have continued without that action. Check the run's status and output before sending a follow-up; the tool raises a new request if it still needs one.

A Sync Shows Recovery Needed Or Confirmation Overdue

Open the sync detail in Sync activity and read the description under the status.

Recovery needed: the sync could not be confirmed safely. Open the destination device and follow the on-screen recovery steps. The device must be reachable and signed in.

Rolled back: the device already restored the previous files. No further action is required unless the sync is still needed.

Confirmation overdue: the device did not confirm the result in time. Check that the destination device is online, signed in, and running the background service, then check its recovery status in the sync detail.

A Matrix Task Stays Waiting For A Device

A task assigned to a native AI tool shows "Waiting for [device] to pick this up" when the assigned tool's device has not yet claimed the run. If the status shows the device is offline, reassign the task to a different device or tool to continue. See Matrix conversations for reassignment steps.

A Task Conversation Reached Its Limit

One of two messages appears when a conversation can no longer continue:

  • File or context limit (task conversation): "This task conversation has reached its file or context limit." Remove files from the current draft or shorten the message. Previous records are preserved.
  • Context window full (onemind agent): "At 100% onemind can't reply. Start a new chat to continue." Start a new onemind agent chat to continue.

See Matrix conversations and The onemind agent for details.

Minds Are Read-Only

If Mind edit and submit actions are blocked and the panel shows that Mind changes are temporarily read only, the team's active member count exceeds the plan's seat limit. Write access returns when members are removed to bring the count within the limit, seats are added to cover the current membership, or the plan is upgraded. See Plans and billing for seat and plan options.

A Payment Is Still Confirming

After completing checkout, the product shows a confirming state while the server waits for Paddle's verified confirmation. This normally resolves within a few seconds. If the confirming state persists after several minutes, reload the page or sign out and back in. If the plan does not activate, contact support from Support. See Plans and billing for billing details.