Troubleshooting

This page is organised by symptom. Two things fix a surprising number of issues, so try them first: restart ORG-2, since several subsystems only probe your environment at startup, and read ~/.orgii/logs/orgii.log for the error that was actually raised.

Install and launch

macOS refuses to open the app

Official macOS releases are Apple Silicon builds, signed with a Developer ID certificate and notarized, so Gatekeeper should accept the .dmg silently. If you still see "cannot be opened because the developer cannot be verified", either the download did not come from the official releases page, or you built the app yourself — local builds are unsigned and get quarantined, so right-click in Finder, choose Open, and confirm once.

There is no Intel (x86_64) macOS build. On an Intel Mac, build from source.

Windows shows a SmartScreen warning

Windows installers and MSIs are signed through Azure Trusted Signing. If SmartScreen still shows "Windows protected your PC", confirm the file came from the official releases page, then choose More info → Run anyway. Never bypass it for a binary from a mirror or a chat message.

There is no Linux download

The release workflow builds macOS (Apple Silicon) and Windows (x64) only — there is no published AppImage, .deb, or .rpm. On Linux, build from source with Node.js 20+, pnpm 9.15, Rust 1.85.0 or later, Python 3, and your distribution's Tauri prerequisites:

pnpm install
pnpm run download:sidecars
pnpm run tauri:dev

Agents and CLIs

An agent will not start, or a CLI shows "Not installed"

Settings → Dependencies and Settings → CLI Agents show Installed or Not found per tool, with a detected version. A CLI you know is installed but that reads as missing is almost always a PATH problem: on macOS an app launched from the Dock or Finder starts with a stripped PATH that hides Homebrew, nvm, fnm, pipx, uv, and cargo installs. ORG-2 works around this at startup by asking your login shell for its real PATH ($SHELL -i -l -c 'echo $PATH', then $SHELL -l -c 'echo $PATH') and appending /opt/homebrew/bin, /usr/local/bin, ~/.local/bin, and ~/.cargo/bin when they exist. The probe times out after five seconds, so a blocking rc file leaves only those directories.

1. Confirm the CLI resolves in a fresh terminal (which claude, which codex).
2. If it does, put the binary or a symlink into one of the directories above, or move the PATH export into ~/.zshrc.
3. Restart ORG-2. The probe cache at ~/.orgii/dependencies.json is cleared at startup, so a restart forces a rescan; Settings → Dependencies also has a refresh action.

If the wrong version is picked up, remove the stale copy from PATH.

Browser Use or Computer Use is unavailable

Both need optional native sidecars that are deliberately not bundled in the notarized app and never downloaded at startup: agent-browser for browser automation (macOS, Linux, Windows) and peekaboo for desktop automation (macOS only). Install them explicitly:

• Packaged app: Settings → Built-in Tools → Computer Use → Sidecar Downloads → Download. Binaries land in ~/.orgii/bin/; Refresh status re-checks and Last error explains a failure.
• From source: pnpm run download:sidecars, which installs into src-tauri/bin. A missing sidecar only gets a build-time placeholder, so the capability stays off until you download it.

To use your own build instead, set Agent Browser CLI Path. Computer Use additionally needs macOS Accessibility permission — Settings → Computer Use shows Granted / Not granted and a re-check action.

Keys and authentication

A key shows "Invalid keys" or "Suspended - API key failed"

Open Settings → Models & Keys and re-validate with Auto-detect / Validate. If the provider revoked or rotated the key, the edit form deliberately will not let you patch it in place — remove the account and add a new one.

A CLI agent's subscription login stopped working

Subscription logins (Claude Code, Codex/ChatGPT, Gemini, Cursor) store OAuth tokens locally and expire. Re-run the sign-in flow in Settings → Models & Keys, or use the agent's detection action — Codex reads ~/.codex/auth.json and OPENAI_API_KEY, Gemini reads ~/.gemini/oauth_creds.json and GEMINI_API_KEY. Detection needs the CLI installed and logged in at least once.

You are being rate limited

ORG-2 retries automatically, showing API rate limited, retrying... with an attempt count and a hint to switch windows while it backs off. Persistent limiting usually means an exhausted plan — Quota Info on the key shows plan, usage, limit, and reset date where the provider reports them.

Proxies, VPNs, and corporate TLS

Settings → Device & Network shows detected region, per-domain request stats, VPN status, and Git Proxy. Set HTTP Proxy / HTTPS Proxy there when git fails behind a corporate proxy — a proxy currently coming from environment variables gets written into your global git config when you save. If model requests hang on a TLS-intercepting network, switch HTTP Version from Auto (recommended) to HTTP/1.1 only.

Signing in to ORG-2 Cloud

The browser signs in but the desktop app never comes back

Cloud sign-in is a bridge: the desktop app opens the hosted login page with a return_to value, that page emails a magic link, the link lands on /auth/callback, which verifies the code in the browser and forwards to /auth/desktop with session tokens in the URL fragment only, which hands off to the app. If you get stranded on the "Signed in" page:

1. Click Open ORG2. That button exists for browsers that block automatic navigation to custom URL schemes.
2. Make sure ORG-2 is running and was installed, not just built — the app registers the orgii:// scheme with the OS, and an unregistered scheme silently does nothing.
3. Open the magic link in the same browser that started sign-in, on the same machine: the code exchange is client-side and needs that browser's PKCE verifier, and the callback only reaches a local process.

"No session found in this link" means the fragment was stripped; start again from the desktop app. Isolated local instances use orgii-instance2:// through orgii-instance99:// instead of plain orgii://, and only those exact callbacks are accepted — anything else fails closed, so a return_to typo produces exactly this symptom.

Sessions

A session looks stuck

Use Stop agent process in the session sidebar, then read the last events in the trajectory panel — a frozen-looking session is often waiting on a permission request or an Ask user question that scrolled out of view.

A shell command hangs

ORG-2 does not kill long commands. After Command Timeout seconds (per agent, 1–600) it backgrounds them and keeps them running, expecting the agent to check on them with run_shell plus cat/tail or kill them. You can also stop one with the Stop control on the shell tool call.

High CPU or RAM

Settings → Device & Network → Performance Monitor splits usage into backend RSS, WebView renderer, GPU and networking helpers, and terminal/tool helpers, and lists live Child Processes plus a 30-minute RAM History. Tool helpers dominating usually means an agent left background commands running.

Very long sessions slow down or lose earlier context

With Context Compaction on, older messages are summarized while recent ones stay verbatim, and the chat warns Context will be summarized soon first. Tune Trigger Ratio, Keep Ratio, and Summarization Model. With it off, ORG-2 silently truncates instead — usually what "the agent forgot" means.

Replay

Replay is empty or missing events

• "No events yet" means the session recorded no activity — replay renders the event log.
• Old sessions lose events. Housekeeping prunes sessions and events rows older than 30 days, and browser screenshots after 7 days.
• A shared session shows metadata only. Ask the owner to raise its access to Full replay.
• Filters hide events. Reset the replay event filter to All events before concluding data is missing.

Git and worktrees

Push, pull, or fetch fails with an authentication error

ORG-2 shows a GitHub authentication required dialog with inline recovery: load from the macOS Keychain or a git credential helper, or paste a username and personal access token. For a durable fix use Settings → Integrations → Git — connect GitHub, save a token, or use Detect from System (gh CLI, SSH keys, credential helpers). An expired token reports "Your GitHub token has expired" and reconnects in the same place.

A branch is "checked out in worktree"

Sessions can run in isolated git worktrees, and git refuses to check out one branch twice. The branch selector marks these In use and shows the worktree path. Switch to that worktree, or use Remove Worktree, which deletes the checkout but keeps the branch and commits.

Dirty repo state

If a session leaves uncommitted work, the source-control panel offers Stash and View Stash to reach a clean tree without discarding anything. To throw a session's work away, use Discard worktree — it cannot be undone. Worktrees whose session no longer exists are evicted automatically.

Logs, app data, and diagnostics

Everything ORG-2 writes lives under ~/.orgii/.

Rotated logs are pruned after 30 days. Settings → Storage exposes Data Directory and Log Files with Open folder; Settings → Device & Network → Disk Usage breaks the directory down by category with a per-category clear action.

For more detail, set RUST_LOG before launching ORG-2; it overrides the default filter (info, with key_vault and agent_core at debug). Panics are captured by a dedicated hook, so a crash leaves a === PANIC === block with a backtrace.

Filing a good bug report

Open an issue at github.com/org2AI/ORG2/issues with your ORG-2 version (Settings → App Update → Current Version), OS and architecture, whether you installed a release or built from source, exact reproduction steps, the slice of orgii.log and frontend.log around the failure, and a screenshot for anything visual. Redact keys and tokens first. For a security vulnerability, do not open a public issue — follow SECURITY.md.

Getting help

• Discord: discord.gg/tvWgAqhCzs — #how-to-use-org2 and #faq for setup and usage, #feedback for ideas and bug reports.
• GitHub issues: github.com/org2AI/ORG2/issues for reproducible bugs and feature requests.

Next steps

• Install — platform requirements and first launch.
• API keys — adding, validating, and rotating provider keys.
• Sessions — how sessions run, pause, and resume.
• Replay — reading a recorded trajectory.