# Find the failing part

Start with the exact operation that failed. A missing tool, an empty search, a failed login and a stale code map need different fixes. Don’t reinstall everything before you know which one you have.

## Memory works, but the CLI fails {#connection}

That is possible because they use separate connections. Your assistant authenticates to the MCP service. The CLI authenticates independently on the Mac where it runs.

Check memory with the assistant’s real `agent_search` tool. Check the CLI with `korium-cli status`. Do not remove a working MCP connection to repair the CLI’s keychain sign-in.

## The login keeps asking again {#authentication}

Record the client version, service address, time and exact error. Check whether the failure happens during discovery, browser authorization, the local callback, token exchange or refresh. Those observations are more useful than guessing a token lifetime.

Update an outdated client and retry the failing operation once. If reauthorization is needed, use that client’s own login: `codex mcp login korium` for the Codex MCP entry, `/mcp` in Claude Code, or `korium-cli login` for the Mac CLI. Keep these flows separate.

If the error names an authorization-server issuer, inspect whether the client retained the issuer and discovery metadata in the format it expects. A field being present somewhere in a response does not prove the client stored it correctly. Don’t paste the raw credential file to demonstrate it.

A refresh token can be rejected for reasons other than age, including revocation, rotation races or mismatched client state. Keep the failure evidence and ask for help if a fresh connection repeatedly breaks.

## The tool is missing {#tools}

Confirm the connection is enabled in the host running the task and that it requested the required scopes. A read-only token will not expose writing tools such as capture. The tool prefix may differ from the name in another assistant.

Use the live tool list. Don’t type a tool name from somebody else’s screenshot and assume it must exist in your client. Reauthorize with the appropriate scope only if the connection should have that permission.

## Search is empty or returns the wrong material {#search}

Check the workspace, then the scope, then the question. Search for distinctive words from a known memory and compare with a browse operation. Confirm the earlier capture actually returned a successful memory ID.

A new capture may still be undergoing background extraction or indexing. A search can also report a partial or degraded path. Read that status rather than treating it as a normal full result.

If the result is factually wrong, check the source and replacement chain. A confident answer is not a reason to overwrite a reviewed decision.

## The save returned an ID, but the next step is not ready {#processing}

Keep the receipt and the exact operation that did not work. Saving, search, graph links and code publication have different completion checks. Do not submit repeated copies of the same material while diagnosing a read.

<div class="table-scroll"><table><thead><tr><th>What you see</th><th>What to check next</th></tr></thead><tbody><tr><td>Capture refused or no successful receipt</td><td>Read the error or rejection class. Fix permission, allowance or payload before treating it as saved.</td></tr><tr><td>Capture receipt, but no expected search hit</td><td>Compare workspace and exact scope, search distinctive wording, and inspect the record with browse after processing.</td></tr><tr><td>The record is present in history but has <code>invalid_at</code></td><td>It is no longer current. Browse with <code>status: "invalidated"</code> and inspect any replacement links; expiry, supersession and duplicate processing are different possible causes.</td></tr><tr><td>Both an original and its correction are inactive</td><td>The correction exercise has not passed. Keep both IDs and the trace; ask support to inspect the reason and surviving replacement rather than saving a third copy.</td></tr><tr><td>Search marks a result provisional</td><td>Use it with its source, but do not report that later processing has completed.</td></tr><tr><td>Search reports partial or entities_partial</td><td>Read the explanation and distinguish incomplete retrieval from unavailable related context. Do not infer an exact zero.</td></tr><tr><td>Correction saved, but relation or trace failed</td><td>Keep both IDs. Confirm both records are available to the relation operation, then verify the link; do not create another correction merely to retry it.</td></tr><tr><td>CLI finishes, but the indexed commit is old</td><td>Publication remains unverified. Follow the final CLI message and check a known symbol at the expected commit.</td></tr></tbody></table></div>

A timestamp alone does not identify the cause. Some client responses do not expose the invalidation reason or the memory a duplicate folded into; report that missing visibility rather than inventing a diagnosis.

If processing does not settle, send the time, receipt ID, client version and exact failure through the support path. Do not send the private memory content unless you have agreed to share it.

## Code search points at the wrong version {#code}

Read the indexed commit and compare it with `git rev-parse HEAD`. Verify returned candidates in the local file before using the line range. An older index can still be useful, but it is not proof of the current implementation.

An unknown repository needs the correct identity or its first index. An unindexed commit needs an update. An unsupported file type needs local text search. Don’t solve all three by repeatedly changing the wording of the query.

Each branch has its own index. Read the branch named in the answer as well as the commit. A search that names a branch Korium holds no index for searches nothing and lists the branches it does hold; so does a search that names no branch in a repository with no trunk index, for example because it was deleted. Index the branch you need, or name one of those listed. When an assistant’s `code_locate` answer says the index is missing or behind, its `next_step` says to run `korium-cli index` in the checkout.

`korium-cli index --retrack` is gone. korium-cli refuses it and sends nothing, because there is no single index to move between branches. Run `korium-cli index` from the branch you want indexed.

If you used `--no-wait`, check whether publication completed. “Accepted” and “searchable” are separate stages.

## The Mac CLI cannot run or sign in {#cli}

Check `korium-cli version` and the installed path. Use the supported package from your dashboard rather than a copied standalone binary. The installed app’s signing and keychain access matter.

You don’t need to run `korium-cli login` before other commands. `index`, `search`, `delete` and `repos` open the browser sign-in when this Mac is not signed in, or when Korium no longer accepts the saved sign-in, and then carry on. If you decline, or don’t finish within three minutes, the command stops and nothing is sent. Run it again when you are ready.

Compare `status` in a normal terminal with the same command in the failing execution context. A sandbox or background service can have different keychain access. Grant only the access that setup needs; don’t solve it by exporting a token.

If indexing is refused, read the stated reason. A removal guard, capacity limit and invalid repository root are not authentication failures. Preview with `--dry-run` before changing the scope or permitting removals.

## The hook is silent or will not stop {#hooks}

Confirm the file exists where the configured command resolves, the project is trusted and the required tools are on PATH. Run the script with sample input outside the agent to separate a script failure from a client configuration problem.

Keep JSON stdout clean for hooks that expect it. Send diagnostic output to stderr. Check `stop_hook_active` before asking a Stop hook to continue again.

Korium’s Git hooks and the Claude Code Stop hook from `korium-cli hooks install` never wait for a sign-in. On a Mac that is not signed in, they open the sign-in in your browser in the background and finish at once. If you declined that sign-in within the last hour, or the Mac cannot open a browser, as over ssh, they print one line saying the index was not changed and to run `korium-cli login` instead. Run any korium-cli command yourself and the hooks may ask again.

The provided task-end script reports an indexing failure and allows completion. If you add a stricter memory reminder, test unavailable-service and quota-refusal cases as well as the happy path.

## What to send us {#support}

- The command or tool that failed, without credentials.
- Your client and CLI versions, operating system and server address.
- The exact error, time and any request ID.
- Whether the same operation works in another execution context.
- The indexed commit and requested commit for a code-search problem.

Remove private memory contents and customer source material unless you have explicitly agreed to share them. Send the useful diagnostic details to [robert@kyroco.ai](mailto:robert@kyroco.ai).