---
title: "Troubleshoot Cortex"
canonical: https://workspace.socra.com/docs/cortex/troubleshooting
---

# Troubleshoot Cortex

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

## The setup command detects no agents

The [`socra cortex setup` command](/docs/cortex/integrations/coding-agents#install-automatically) 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. See the [Cortex MCP endpoint reference](/docs/cortex/reference/mcp#endpoint) for connection details.

If you are configuring a custom client, verify its client type, redirect URL, and OAuth credentials against the [custom MCP guide](/docs/cortex/guides/mcp). A first-party plugin does not require you to create or enter a client secret.

## CLI commands fail or return incomplete data

Update the [CLI and its installed namespaces](/docs/cortex/reference/cli):

```bash
socra update
```

Retry the same command. A stale Cortex CLI can produce failures that resemble a backend outage, including incomplete [Module](/docs/cortex/concepts/modules-and-map) or [Issue](/docs/cortex/concepts/issues-and-coordination) results.

## The agent does not use Cortex knowledge

Confirm that the agent called a Cortex tool and [flashed the relevant Module](/docs/cortex/concepts/flashing-context). 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.