Skip to main content

Troubleshooting

Start with the visible status in the sidebar, Overview, transcript, run board, Activity and Attention, or Runs. Locus reports the failing layer rather than silently changing routes.

Local services or Ollama are unavailable​

Wait for Starting or Recovering to finish. Confirm Ollama is installed and reachable at the configured host. A local model loads on the first prompt and may reload after a context-window change.

ChatGPT sign-in or component fails​

Open Settings → Updates and confirm the Codex component is installed. Retry the component download on a stable connection. A checksum or code-signature failure installs nothing; remove and reinstall the component if the verified archive is incomplete. ChatGPT-plan routing never falls back to an API key.

If /compact appears ineffective, update to the current release; compaction resets the helper's server-side thread too.

ChatGPT behavior changed after the update​

Open the account editor and check Codex-native mode. New accounts begin with Locus's prompt and tools; accounts added before 2.1 keep their previous choice. Turning the toggle on or off restarts the conversation's server-side context, and the first message in an existing chat may replay history once.

Reasoning effort applies on the next turn without a reset. Web search is a separate, off-by-default toggle.

A hosted account will not switch​

Test the account, URL, key, and selected model. Kimi and Kimi Code use different hosts and credentials. Authenticated custom endpoints require HTTPS and cannot redirect. A rejected switch should restore the previous active route. Update to the current release if a ChatGPT or Kimi model is incorrectly reported as not installed.

A model answers but cannot edit or see images​

The route may lack tool calling or image input. Locus retries once without the rejected capability and records a note. Choose a tool-capable or vision-capable model for that request.

A note opens empty​

Update to the current release before typing into it. Locus now falls back to the formatting archive when the plain-text mirror is missing. Open Notebook with ⇧⌘9; older notes that cannot be matched to an existing owner appear under Unlinked.

Browser input, layout, or Autofill fails​

Refresh the page snapshot before reusing element identifiers. For a canvas or map, capture the region and target page coordinates. Confirm real input is enabled under Settings → Browser. Reload after changing the mobile-device presentation because sites choose their layout at navigation time.

Resize the inspector after updating to the current release; the live page should follow the panel and wide pages should keep native horizontal scrolling.

For Autofill, confirm the vault is loaded and the required category is enabled for agent access. Passwords are origin-scoped. Browser JavaScript and dev-server startup require approval even in Bypass.

Wallet controls are missing​

This is expected in standard Locus: the app is wallet-free. Cryptocurrency wallet functionality belongs to the separate LocusX edition. Old wallet files and Keychain entries are not deleted or automatically migrated. Identity Vault is a separate private profile-and-document feature.

A named dev server will not start​

Validate .locus/launch.json, executable, arguments, and port. Use a URL-only configuration to attach to an existing server. Read the bounded server output with a level or search filter.

Mobile will not pair​

Enable Mobile Access on the Mac, keep Locus or its menu-bar process running, and use a fresh five-minute code. Confirm both devices can reach each other over the LAN or Tailscale. A changed Mac certificate requires a new pairing.

A command needs a full terminal​

Use Terminal for interactive programs. Managed background services are better for watchers and servers that should survive an agent turn.

A run shows the wrong files, steps, or usage​

Update to the current release. Overview and Activity are scoped to the selected run even when another run is live. Switch away and back if you were viewing data loaded by an older build.

A team plan is repaired or a run reaches a limit​

Open the board or Runs for the exact validation or budget boundary. Writer-step and model-call limits pause at a durable checkpoint; they are not success conditions. Repair the missing profile, credential, checkout, or budget and resume.

Proxy traffic fails​

Run a profile health check. In strict tunnel mode, external traffic remains blocked until a healthy route exists. PAC-based system proxy settings may not reach agent libraries; use a manual profile. A child process can report 407 because Locus withholds proxy passwords from it.

Still blocked?​

Record the Locus version, build channel, provider and model, visible error, and relevant Runs timeline. Do not include credentials. Report security issues privately to contact@locushost.co.

An Agent is active but no chat is running​

A saved agent can be available while its chat is idle or a trigger is waiting. Inspect the next occurrence or incoming-event record, connection health, and exact execution status. A received, waiting, or skipped record is not a completed run. Ordinary local work requires Locus to remain running; independent continuation additionally requires the service and the agent's explicit opt-in.

A goal has paused​

Check whether the mode, account, team, allowance, or connection changed. Review any interrupted action with an unknown outcome before Resume. Required questions need a real answer; elapsed time is not approval.

A Task Capsule will not run​

Check the selected profiles, account availability, and implementation access ceiling. If a named file changed after planning, use Update the plan or ask for help to save a revision. Review partial file changes before starting another run.

A document or output is missing​

Enable Document knowledge for persistent document search and check the extraction status. Older DOC/XLS files need conversion; formulas without saved values and hidden spreadsheet sheets are omitted with warnings. Retry an extraction after correcting the source.

In Outputs, inspect the workspace storage budget and per-file limit. Missing originals cannot be reconstructed from older entries unless a version was already saved. Existing history remains available when limits are reached.

The app does not update automatically​

If you use 2.6.0 or earlier, install the current Locus 4.0.0 release manually once. Use Check for Updates in the sidebar gear menu or check Settings → Updates: previously disabled automatic checks or downloads stay disabled until you change them. A downloaded app update normally installs when you quit. Managed-account component updates are separate from the application.

Resume companion setup or connect a model​

Use Help → Getting Started, the left Companion row when none is configured, or Set up your companion in the right-rail panel. Setup keeps an unfinished draft and is not offered automatically on every launch. Once configured, the sidebar row opens the companion's normal conversation. A ready character without a model is expected: connect an account/model through the profile's existing controls before chatting. Repeating setup is not needed. See Your companion.

Memory needs recovery​

An unavailable memory count is not an empty vault. Read the restore-protection message in memory settings. Unlock a locked login Keychain; if a backup lost newer deletion history, restore the newer ledger or follow the authenticated offline recovery procedure. Do not delete checkpoint items to bypass protection. Workspace Knowledge & Memory explains the limits.

Earlier wallet-era installations keep their unchanged feed. Local development builds may use manual updates.

Overview or attachments seem to have moved​

Overview now appears near the top right during work and yields to an open inspector. Use ⌘1 or the workspace menu to reopen it. The panel toggle restores your previous inspector. Attach files through the composer or Overview → Sources; use Context for the detailed usage breakdown.

Image generation is unavailable​

Choose a supported image account in Settings → Models & Providers → Image generation. Select the image account explicitly, even if that account is already used for chat. In 3.0, a ChatGPT image account uses GPT Image 2 with automatic size and quality; API accounts use their supported model settings. Claude plan is not an image provider. Check the visible status, selected model, and account readiness. If the current turn is busy, the changed image settings may apply when that turn ends. You can stop an in-flight generation with Stop.

An interactive answer shows only text​

Check Render interactive answers in the image-generation settings. Interactive rendering has its own capability and does not require an image account. Mobile and exported conversations use the written summary; the HTML can also be saved separately.

Claude plan is missing or cannot sign in​

Claude plan is a separate preview account. Confirm its managed component is installed and that the host advertises the capability. Standard portable candidate packages include Codex only; a remote package needs the optional verified Claude helper to offer Claude plan.

Use the account's managed sign-in flow, not an API key or copied local Claude credentials. Remote accounts sign in independently. Full authentication, expiration, clean-machine distribution, and remote scenarios retain open preview gates; see Hosted & Custom Models.

If a managed response ended without a settled result, inspect files and external actions before continuing in a new or forked task. An uncertain action cannot be silently replayed.

Duo is waiting or uses a different model than the header​

Duo keeps its task's Plan with and Build with pair even if the ordinary model picker changes. The plan needs Accept & build before implementation. Use Revise for changes, Retry saving plan after a save failure, or Review recovery for an interrupted build. Switch to Work for ordinary messages with the header's model. An unavailable stage account stops the handoff rather than choosing a fallback.

A task says Needs review after the agent reported success​

Inspect task details for missing or stale checks, an unresolved reviewer finding, an uncertain action, or a criterion that needs human judgment. Written success is not execution evidence. Retry checks rechecks existing outputs; Resume continues the attempt; Run again deliberately starts new execution. Accept result records your acceptance separately from machine verification.

Changing files or requirements can invalidate prior evidence. Exhausted allowances, missing reviews, and unknown action outcomes remain incomplete. See Task Recovery & Restoration.

A restoration preview will not apply​

Refresh the preview after any task or file change. Another active chat using the same execution location blocks restoration. Conflicting files, unsupported shell edits, unsafe paths, and oversized or uncaptured content remain excluded. Select only the eligible files. If restoration was interrupted, use its explicit recovery or undo controls; reopening alone does not change files.

A reusable check did not apply​

A proposal must be explicitly approved before future tasks select it. Confirm its project, optional file scope, agent/chat scope, and approved version. Existing tasks retain their saved versions; editing or disabling a check changes future admissions. Use Apply to this task where offered, or the goal/capsule's own requirement controls. A test waiting on command permission must be approved through the existing task prompt.

Independent work stopped after closing Locus​

Check Settings → Runtimes, the background-service registration, and Keep running when Locus closes on the selected worker. Enabling the service does not opt in all workers. The Mac must remain awake and logged in. Desktop browser and computer requests wait for Locus's native broker. LocusX builds do not install the independent runtime.

For Linux hosts, confirm the systemd user session and lingering requirement before expecting work after SSH logout. A remote Mac also requires an active graphical login. SSH & Remote Runtimes lists deployment requirements and the candidate-package release limitations.

SSH deployment or returned changes fail​

Use Validate host and resolve host-key mismatches through your trusted SSH configuration. Choose a package for the exact OS/architecture and its reviewed checksum. A wrong, modified, or incompatible archive is refused. Confirm account readiness and sign subscription accounts in independently on that host.

Use Recover deployment for an interrupted deployment record. Retrieve result does not apply returned files. Select files and use Apply selected changes; changes to the local baseline require review instead of overwrite. Removing a connection leaves remote work and credentials on the host.

A runtime update is blocked or interrupted​

Pause and drain active work before installing. Candidate startup blocks new work until it passes package and service checks. Failure attempts to restore the previous service and databases. Interrupted recovery retains a journal and blocks admission; retry installation to reconcile it. Do not delete the recovery journal to force new work. Previous packages and database backups are intentionally retained.

Cost totals show unknown or partial coverage​

Subscription usage is not API billing, and missing prices are not zero. Interrupted calls, unknown prices, and unpriced tool charges can leave partial coverage and pause estimated spending controls. Reconcile only with actual usage evidence. Task and invocation totals overlap and should not be added together; see Usage, Router & Proxy Profiles.