15. Troubleshooting & Common Pitfalls

This chapter collects the most common problems, their causes, and their fixes, along with a few designs that are "working as intended" but easy to find alarming the first time you hit them.

15.1 Quick Troubleshooting Table

15.2 Design Pitfalls Worth Knowing

The following are not bugs — they're intentional:

serve and cli aren't "mutually exclusive," they "take over"

When a omicos serve instance is already running in the workspace, omicos cli connects directly to it, sharing the same session history. Only when there's no daemon in the workspace does cli start its own — in which case it uses .omicos/cli as its data directory, isolated from serve's history.

Similarly, typing omicos serve again in a workspace that already has a running instance doesn't error out — it reuses that instance, opens the browser, and exits successfully:

[omicos] already running in this workspace (pid 41287, port 5055); reusing it instead of starting a second instance.
[omicos] open: https://app.omicos.cn/#/?ws=127.0.0.1%3A5055&auto=true

(Only an instance started by the desktop app exits with an error on conflict — that's left for the desktop side to handle itself.)

The port may not be 5055

If the specified port is taken, omicos searches forward from the next one, up to 100 ports, and only falls back to a system-assigned random port if none of those work. Always go by the listening: line (or the Local line in the dashboard) — don't assume 5055. In scripts, use --report-port to read the actual port.

.kernel_choice overrides OMICOS_KERNEL_PYTHON

In interpreter resolution, a persisted choice (<current directory>/.omicos/.kernel_choice and ~/.omicos/.kernel_choice) ranks ahead of environment variables. If you exported a variable and it doesn't seem to take effect, check what omicos env doctor reports first, then go clear that file.

OMICOS_ENV_DIR doesn't change where the environment installs

It only participates in interpreter resolution. omicos env setup always installs to ~/.omicos/env. To relocate it entirely, change OMICOS_LOCAL_HOME.

--upstream-base-url doesn't determine kernel location, and doesn't enable cloud access

It only configures a local HTTP proxy fallback (forwarding unmatched /api/* requests to the backend). The kernel is always provided by this omicos process itself, unless you explicitly point elsewhere with --kernel-base-url; cloud access is determined by whether the daemon holds a process token (from omicos login). Setting only --kernel-base-url without --upstream-base-url produces a warning but doesn't affect operation.

Environment problems surface lazily

When the Python environment isn't set up, the daemon still starts fine and chat still works — the error only shows up once you actually run analysis code. So run omicos env setup first.

Switching accounts re-registers process identity

When you switch login accounts within a workspace, the cloud doesn't let the new account take over the old account's process identifier. omicos handles this by rotating the workspace_id and re-registering under the new identity, entirely within the running process — no restart, no exit. What you might see is that the session list starts out empty under the new account — the old local session files are still there, and the old account's records still belong to the old account.

Hitting Ctrl+C too soon can drop unsynced messages

Session sync is asynchronous. If you Ctrl+C / kill right after sending a message, content that hasn't synced out yet can be lost. Wait a few seconds after important work before quitting.

Proxies can intercept local loopback traffic

If http_proxy / https_proxy / all_proxy are set without no_proxy allow-listing loopback, both the kernel's outbound requests and the browser's connection to localhost:5055 can get swallowed by the proxy, showing up as "it just won't connect." omicos prints a bilingual warning at startup when it detects this. Fix:

export no_proxy=localhost,127.0.0.1

Expected output: no output; after restarting omicos, the proxy warning no longer appears at startup.

--debug doesn't work in cli mode

cli's screen is taken over by the chat interface, so --debug / --log-filter are unavailable — only RUST_LOG=... omicos cli works. And an invalid filter expression is silently discarded in favor of the default (with only a single invalid log filter ... line to stderr), so you may not realize the filter never took effect.

Device-code login needs "another already-logged-in device"

omicos cli login needs another device already logged in to an omicOS account to confirm. If all you have is a single brand-new machine that's never been logged in, just use omicos login with email/password — it completes entirely in the terminal, no other device needed.

Some values get handled silently

• OMICOS_CATALOG_SYNC_SECS < 30 isn't clamped to 30 — it's discarded and falls back to 600 seconds; OMICOS_MEMORY_SYNC_SECS < 60 falls back to 3600 the same way.
• URL-type variables should not have a trailing slash.
• For boolean switches, 1 is the safest bet (most also accept true / yes, some accept on; any other value is treated as "off").
• Empty or whitespace-only environment variables are always treated as unset.

Credential files aren't encrypted

cloud_login.json, auth.json, plan_token.jwt, and a2a_keys.json are all plaintext, protected only by 0600 permissions. Never commit them to git, paste them, or hand them to anyone. Windows uses a different permission model, so double-check it there.

15.3 Collecting Diagnostic Information

Before reporting a problem, gather the following:

omicos --version

Expected output:

omicos 0.3.29+a1b2c3d

omicos env doctor

Expected output:

kernel python : /Users/you/.omicos/env/.venv/bin/python3
omicverse     : present ✓
managed env   : /Users/you/.omicos/env
uv            : /Users/you/.local/bin/uv
package index : pypi (https://pypi.org/simple)

omicos login --status

Expected output:

[omicos] logged in as you@example.com
[omicos] process: my-analysis
[omicos] config: /Users/you/.omicos/cloud_login.json

curl -sS http://127.0.0.1:5055/health

Expected output:

{"service":"omicos-core","status":"ok","version":{"build_profile":"release","display":"0.3.29+a1b2c3d","git_rev":"a1b2c3d","semver":"0.3.29","target_triple":"aarch64-apple-darwin"}}

Reproduce with debug logging:

RUST_LOG=omicos_core=debug omicos serve --no-browser > omicos-debug.log 2>&1

Expected output: no output in the terminal (it all goes to omicos-debug.log); the file starts with the startup banner, followed by debug logs line by line. Equivalent to omicos serve --debug true.

15.4 Notes on Offline Mode

With the OMICOS_*_OFFLINE family of switches on, agents / skills / models / memory may be a stale cache that doesn't reflect the latest cloud content. When investigating "why don't I see the new agent," first make sure you're not in offline mode.