Skip to content

Troubleshooting

Jump to bottom
Chuyue Wang edited this page May 19, 2026 · 3 revisions

Troubleshooting

Daemon Won't Start

"Cannot open webcam device"

The daemon failed to find a usable camera.

  1. Check the camera is not in use by another app (Zoom, FaceTime, etc.)
  2. Verify camera permission: System Settings → Privacy & Security → Camera → Terminal.app should be allowed
  3. Test the camera directly: 
    python3 -c "import cv2; cap = cv2.VideoCapture(0); print(cap.read()[0]); cap.release()"
  4. If you have multiple cameras, try hardcoding: add CORTEX_CAPTURE__DEVICE_ID=0 (or 1, 2) to .env

"ModuleNotFoundError" on startup

The virtual environment is not activated or the package is not installed:

source .venv/bin/activate
pip install -e "./cortex[dev]"

Daemon starts then crashes immediately

Check the log output for the specific error. Common causes:

  • Missing .env file: cp cortex/.env.example .env
  • Invalid LLM config: set CORTEX_LLM__FALLBACK_MODE=rule_based to keep running with a deterministic plan when no provider can be reached
  • Missing storage directory: python -m cortex.scripts.seed_config --root .

Camera Issues

Camera opens iPhone instead of MacBook camera

Cortex automatically skips Continuity Camera (iPhone/iPad) and verifies each camera by name before accepting it.

  • Restart the daemon after turning off your iPhone — camera selection runs once at startup
  • If it still picks wrong: set CORTEX_CAPTURE__DEVICE_ID=0 in .env (or try 1, 2)
  • Debug what cameras are visible: 
    python3 -c "
from cortex.services.capture_service.webcam import _list_macos_video_device_names
print(_list_macos_video_device_names())
"

Camera permission denied

  • If launched from the browser extension: grant camera to Terminal.app in System Settings → Privacy & Security → Camera
  • If launched from iTerm or another terminal: grant camera to that app instead
  • Do NOT reset all camera permissions with tccutil reset Camera — this clears camera access for every app on your Mac (Zoom, FaceTime, etc.)

Camera light stays on after stopping

pkill -f "cortex.scripts.run_dev"

If that doesn't work:

lsof -ti tcp:9473 | xargs kill -9

Browser Extension Issues

"Native host not found" or "Access forbidden"

  1. Run the installer: python -m cortex.scripts.install_native_host
  2. Fully restart your browser (Cmd+Q, then reopen) — reloading the extension tab is not enough
  3. Native messaging manifests are only read at browser startup

Extension popup shows "Not connected"

The daemon is not running. Click Start Cortex or run cortex-dev from your terminal.

"Start Cortex" opens Terminal but daemon fails

  • Check Terminal.app has Accessibility permission: System Settings → Privacy & Security → Accessibility
  • Check the Terminal window for the actual error message

Extension ID changed after rebuild

This should not happen — the extension uses a fixed manifest key for a deterministic ID. If it does change, re-run python -m cortex.scripts.install_native_host and restart the browser.

"Stop Cortex" Doesn't Work

The extension uses a multi-layer kill chain:

  1. WebSocket SHUTDOWN message
  2. POST /shutdown HTTP request
  3. Wait 1 second
  4. lsof port scan + pgrep process search → SIGTERM
  5. Wait 3 seconds → SIGKILL survivors

If the stop button fails once, click it again. If the camera light stays on after two attempts:

pkill -f "cortex.scripts.run_dev"

LLM Errors

LLM provider errors

Cortex talks to Claude through the Anthropic SDK. Pick exactly one transport via CORTEX_LLM__PROVIDER:

  • Verify CORTEX_LLM__PROVIDER is one of bedrock, vertex, or direct.

Bedrock (default). Confirm the bearer token is in Keychain and the region is set:

security find-generic-password -s cortex.bedrock -a bearer_token
# CORTEX_LLM__BEDROCK__AWS_REGION must be set in .env (e.g. us-east-2)

If you opt out of Keychain with CORTEX_LLM__USE_KEYCHAIN=false, export AWS_BEARER_TOKEN_BEDROCK into the daemon's environment instead.

Vertex. Re-run the gcloud application-default login flow:

gcloud auth application-default login

The Anthropic SDK reads the resulting credentials automatically.

Direct Anthropic API. Confirm ANTHROPIC_API_KEY is exported into the daemon's environment (the daemon does not read it from Keychain in direct mode).

Fallback. CORTEX_LLM__FALLBACK_MODE=rule_based (the default) keeps the daemon working with a deterministic rule-based plan when every provider is unavailable. Set it explicitly if you want to test without any LLM at all.

See Setup for the full per-provider configuration.

Signal Quality Issues

"No face detected" / rPPG not working

  • Improve lighting — face should be evenly lit, no strong backlight
  • Reduce movement — large head movements corrupt the rPPG signal
  • The system falls back to telemetry-only mode when signal quality is low (this is normal behavior, not an error)

State never leaves FLOW (no interventions)

  • Check signal quality at GET /status/current — if physio quality is < 0.5, the system is in telemetry-only mode with stricter thresholds
  • Run calibration: cortex-calibrate --duration 120
  • Verify the daemon is receiving webcam frames: 
    cortex-capture   # should show video with face detection overlay

Too many false HYPER detections

  • Run calibration (population defaults may not match your baseline)
  • Increase the entry threshold in .env: CORTEX_STATE__ENTRY_THRESHOLD=0.30
  • Check if another app is causing rapid window switching (browser auto-refresh, notifications)

Python / Dependency Issues

MediaPipe import errors on Apple Silicon

pip install --force-reinstall mediapipe

Verify you're using native ARM Python (not Rosetta):

python3 -c "import platform; print(platform.machine())"
# Should print: arm64

pynput / Accessibility errors

Add your terminal app to: System Settings → Privacy & Security → Input Monitoring

The daemon will start without input monitoring but mouse/keyboard telemetry will be unavailable (state classification uses webcam-only mode).

OpenCV camera index errors

python3 -c "
import cv2
for i in range(4):
    cap = cv2.VideoCapture(i)
    print(f'Device {i}: opened={cap.isOpened()}')
    cap.release()
"

VS Code Extension Issues

Context not appearing in interventions

  • Verify the VS Code extension is installed and activated (check the status bar for the Cortex indicator)
  • The extension connects via WebSocket to ws://127.0.0.1:9473 — check the daemon is running
  • Try reloading the VS Code window: Cmd+Shift+P → Reload Window

Desktop App (DMG)

App bounces then disappears

macOS Gatekeeper is blocking the app because it was downloaded from the internet:

xattr -cr /Applications/Cortex.app

Dashboard doesn't show

The dashboard window may be hidden. Check the system tray for the Cortex icon and click it, or try relaunching the app.

Camera not working in .app

Grant camera permission to Cortex.app: System Settings -> Privacy & Security -> Camera -> Cortex should be allowed. If it does not appear in the list, open the app once so macOS registers the permission request.

Cannot connect browser extension

Click the Connect Chrome/Edge button in the desktop app. It copies the install command to your clipboard and opens a terminal window. Follow the clipboard instructions, then fully restart your browser (Cmd+Q, reopen).

Logs

Daemon logs are written to stdout. To save them:

cortex-dev 2>&1 | tee ~/cortex.log

Set log level in .env:

CORTEX_LOGGING__LEVEL=DEBUG   # verbose
CORTEX_LOGGING__LEVEL=INFO    # default
CORTEX_LOGGING__LEVEL=WARNING # quiet

Clone this wiki locally