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

# 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. Plugin skills, supported 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

Read the error before retrying. If access is denied, check the Account and [permissions](/docs/cortex/administration/access-and-permissions). A timeout or service error does not establish that the CLI is outdated.

Compare the command's `--help` output with the current reference. If the installed command or response contract is outdated, update the [CLI and its installed namespaces](/docs/cortex/reference/cli):

```bash
socra update
```

Retry a read command to verify the correction. If a create, update, or delete command failed after sending its request, inspect the resource before repeating it. The first request may have succeeded even when the response did not reach you.

## The agent does not preserve new knowledge

An empty graph after installation is not a connection failure. No Module is required to finish setup. First check whether the agent has encountered something specific and durable during real work: a decision, preference, correction or reason worth reusing.

If it has, ask the agent to diagnose the missing step:

- **Guidance:** Did the host load the Cortex skill, supported SessionStart hook or saved custom instructions? Tools can be connected without this guidance.
- **Access:** Can its current principal edit the relevant Module? Check [Module permissions](/docs/cortex/administration/access-and-permissions).
- **Review:** Is the agent waiting for an approval under your chosen policy, or a host tool confirmation?
- **Meaning:** Is the supposed decision ambiguous, temporary or in conflict with existing knowledge? The agent should resolve that question rather than save a guess.

The remedy is the missing guidance, access or decision. You do not need to start manually authoring Modules to compensate. [Installation](/docs/cortex/installation) verifies connection and guidance separately.

## 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.

If another agent cannot find the same knowledge, check its Account and actual Module access. If the knowledge changed after the current agent loaded it, retrieve the updated Module before repeating the affected work. Saving a correction does not refresh an existing context automatically.

## Knowledge is outdated or contradictory

Give the agent the correction or the new source you are authorized to share. It should compare that evidence with the existing Module, preserve the current decision and reason, and check affected dependencies. If the sources disagree and neither establishes the current decision, it should ask the responsible owner.

An agent cannot keep up with a change it has not seen. Knowledge maintenance happens through the work and material available to the agent; Cortex does not monitor every system or conversation independently.

## The graph grows but the work is not improving

Check a later real task: did the agent retrieve the relevant knowledge and use it correctly? Count the repeated explanations or preventable corrections, not just new Modules. Ask the agent to remove duplication, keep subjects focused and avoid preserving general facts it already knows.

Useful existing artifacts can help a new graph get started, but an indiscriminate import adds noise. Follow [How agents grow your knowledge](/docs/cortex/guides/turn-agents-into-experts) to extract useful specifics from authorized work.