Troubleshoot Cortex

Start with the observable failure, then verify the boundary immediately before it.

The setup command detects no agents

socra cortex setup detects Codex, Claude Code, Cursor, and GitHub Copilot CLI. Confirm that at least one supported host is installed for the same operating-system user.

For command-line hosts, confirm that the executable is available on PATH. Cursor can be detected from its standard user installation even when its command-line launcher is unavailable.

The plugin is installed but Cortex is unavailable

Restart the agent host after socra cortex setup installs or updates a plugin. SessionStart hooks and MCP configuration load when the host starts a new session.

Run socra cortex setup again. A current installation remains unchanged; an outdated installation is updated.

OAuth does not open or complete

Confirm that the host connected to https://cortex.socra.cloud/mcp and follows the resource_metadata URL in the server's 401 challenge.

If you are configuring a custom client, verify its client type, redirect URL, and OAuth credentials against the custom MCP guide. A first-party plugin does not require you to create or enter a client secret.

CLI commands fail or return incomplete data

Update the Socra CLI and its installed namespaces:

socra update

Retry the same command. A stale Cortex CLI can produce failures that resemble a backend outage, including incomplete Module or Issue results.

The agent does not use Cortex knowledge

Confirm that the agent called a Cortex tool and flashed the relevant Module. Assignment, plugin installation, and session start do not preload the complete knowledge map.

Cortex output remains tool context. Check the host's instruction precedence, approval policy, and repository instruction files when the agent retrieves the correct Module but does not apply it.