Troubleshooting.

Practical fixes for the issues we see most often. Each section lists likely causes, then the single most useful thing to try.

App won't launch

The desktop window never appears, or it flashes and closes immediately.

• Another Orchid instance is still running — check the dock / system tray.
• Old user data from a pre-1.0 build is incompatible.
• The bundled Python venv was interrupted mid-install.
• GPU acceleration is unhappy on your driver (rare, mostly Linux).
• The signed binary is being quarantined by a corporate MDM agent.

Quit any background instances, then move ~/.config/orchid aside (rename to orchid.bak) and relaunch. If it still won't come up, run orchid --debug from a terminal — the stderr output will name the failing subsystem. On Linux with GPU issues, try orchid --disable-gpu.

Kernel keeps dying

The Python kernel restarts mid-run, or stops after a heavy cell.

• The process is being OOM-killed — common with large DataFrames.
• A native dependency segfaulted (often numpy built for the wrong arch).
• The bundled interpreter version doesn't match the wheels you installed.
• An infinite loop tripped the watchdog.
• You're on a restricted disk (network mount, snapshot volume) and IPC fails.

Open the bottom panel Kernel tab — it shows memory pressure and the last signal received. If it's OOM, downsample with df.sample(100_000) or push computation into SQL. For mismatched wheels, recreate the venv: delete ~/.local/share/orchid/venvs/<project-slug>/ and re-run any cell — Orchid rebuilds it from requirements.txt on demand.

Agent says it can't see my data

The agent answers as if your DataFrame or connection doesn't exist.

• The notebook hasn't been run yet — variables don't exist in the kernel.
• The agent is reading the project as files only, not live kernel state.
• You're in a different project than you think (check the title bar).
• The connection requires SSH and the tunnel hasn't been started.

Run the cells that define the variables, then ask again — the agent calls kernel.listVariables on each turn and only sees what's currently in memory. For connections, open Integrations and confirm the green check next to your source. See Agents for what each tool can actually access.

Cells stuck running

A cell shows the spinner forever and doesn't produce output or an error.

• An input() call is blocking on stdin that has no terminal attached.
• A network request is hanging without a timeout.
• The result is too large to serialize and the IPC channel is back-pressured.
• You spawned subprocesses that don't flush their stdout.

Press ⌘ . (or Ctrl .) to interrupt — it sends SIGINT to the running cell. If that doesn't take, use Kernel → Restart. Always set explicit timeouts on HTTP calls (requests.get(url, timeout=10)) and avoid input() inside notebooks — use a parameter cell or widget instead.

Publish fails with auth error

orchid publish or the in-app button returns a 401 / 403.

• Your CLI session expired (we rotate tokens every 30 days).
• You're signed in as a different account than the project owner.
• The slug is taken by another user.
• You're behind a proxy that mangles the OAuth callback URL.

Run orchid whoami to see who you're signed in as, then orchid logout and orchid login to refresh. If the slug is taken, pick a new one with --slug <name>. For proxies, use the token flow: orchid login --token <value> after copying a token from orchidide.com/account/tokens.

Connection times out from corporate network

Test connection works at home but fails from the office.

• The database IP isn't reachable from your VLAN.
• SSL inspection is breaking the TLS handshake.
• The corporate proxy strips the PostgreSQL wire protocol.
• SSH tunnel host expects a key Orchid doesn't have access to.

Confirm reachability with nc -zv host port. If TLS inspection is the culprit, install the corporate root CA into Orchid's trust store via Preferences → Network → Custom CAs. For proxies, set HTTPS_PROXY before launching. The SSH tunnel feature reads from ~/.ssh/config and your agent — make sure ssh-add -l shows the key you need.

Chart cell renders blank

A chart cell loads but the canvas stays empty.

• The bound DataFrame doesn't exist yet — re-run upstream cells.
• All values in the chosen column are NaN.
• The aggregation reduces to zero rows.
• A custom Plotly trace silently errored — check the cell's expand-trace section.

Click Show source on the chart cell to see the Plotly figure JSON. If data: [], the upstream query produced nothing — fix the filter. For NaN, use df.dropna(subset=[col]) before binding.

"Module not found" despite installing

You ran pip install but imports still fail in the notebook.

• You installed into the system Python, not Orchid's venv.
• You're in a different project than the one whose venv you installed into.
• The kernel started before the install finished and cached the old import path.

Always install via the in-app Packages panel — it targets the active project's venv. After install, restart the kernel with ⌘ ⇧ R. To install from the CLI, use Orchid's pip wrapper: orchid pip install <package>.

Slow SQL completion

Schema-aware autocomplete takes more than a second to appear.

• The schema cache is stale and being rebuilt.
• The warehouse has thousands of tables and indexing is paginating.
• The connection profile turned off auto-introspection.

Open the schema browser and click Refresh — it forces a full re-index in the background. For huge warehouses, scope the profile to specific schemas in Integration → Settings → Browse scope so introspection isn't traversing the whole catalog.

Real-time collaboration desyncs

You and a teammate see different cell content on the same notebook.

• One client lost websocket connectivity for > 30 seconds.
• You edited an unrelated file outside Orchid in the meantime.
• A soft-lock didn't release after a crash.

Close and reopen the notebook on the desynced client — Orchid will pull the canonical version from the backend. Soft-locks release on blur or after 30 seconds of idle, so a stale lock clears on its own quickly. If you need to claim a cell sooner, the owner can release it from Cell menu → Release lock. Full details in Real-time editing.

App update keeps failing

The auto-updater downloads but fails to apply.

• The app is running with insufficient permissions to replace its own bundle.
• Antivirus is locking the new binary.
• Disk full or a quota limit on the install volume.

Quit Orchid, then re-run the installer manually from orchidide.com/download. On macOS, make sure Orchid lives in /Applications, not under a per-user folder. On Linux, re-symlink the new AppImage to the same path.

Reading the logs yourself

The log directory mirrors the subsystems. On macOS logs live at ~/Library/Logs/Orchid/; on Linux ~/.config/orchid/logs/.

main.log         # the desktop shell
kernel.log       # bundled Python process
agents.log       # LLM calls, tool invocations, costs
backend.log      # backend API client (publish, login)

Lines are JSON, so jq works for ad-hoc queries — e.g. jq '.level' agents.log | sort | uniq -c.

Still stuck?

Email hi@orchidide.com with your Orchid version (About menu), OS, and the last 50 lines of the relevant log. We read every message. For account, billing, or publishing issues, see the FAQs.