> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xysq.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common errors, exit codes, and how to fix them.

## "No API key found"

The CLI couldn't find a stored key, you didn't pass `--api-key`, and `XYSQ_API_KEY` isn't set in the environment.

**Fix:**

```bash theme={"dark"}
xysq login                           # interactive paste
# or
xysq install --api-key xysq_...      # one-shot
# or
export XYSQ_API_KEY=xysq_...
```

If you're running in a non-TTY environment (CI, dotfiles bootstrap), the CLI exits with code 3 instead of prompting — you must supply the key via flag or env var.

## "Your stored xysq API key was rejected"

The key in your keychain is no longer valid — maybe it was revoked from the dashboard, or you've signed in as a different user since it was generated.

**Fix:**

```bash theme={"dark"}
xysq login --replace                 # paste a fresh key
xysq install                          # re-sync every wired agent
```

## "`<file>` is malformed JSON/TOML"

The CLI refuses to touch a config file that doesn't parse. This protects you from a clobbered file when the agent's config is mid-edit or has a stray syntax error.

**Fix:** open the file, find the parse error (the message includes line/column), repair it, then re-run `xysq install`.

## "Permission denied" on a config file

The CLI couldn't write to an agent's config file.

```
✗ Cannot write ~/.codex/config.toml (Permission denied)
  Diagnosis: file is owned by root (perhaps installed via system package).
  Fix: `sudo chown $USER ~/.codex/config.toml` then re-run `xysq install codex`.
```

The CLI's error message includes a copy-pasteable fix when it can diagnose the cause.

## "block edited locally" warning from doctor

You manually edited the content inside the `<!-- xysq:start --> ... <!-- xysq:end -->` block of a shared host file (`AGENTS.md`, `GEMINI.md`, `.cursorrules`). The CLI flags this as drift rather than silently overwriting your edit.

**Fix (you want to keep your edit):** ignore the warning. Edits inside the block persist as long as you don't re-run `update-skills --force`.

**Fix (you want the CLI's version back):**

```bash theme={"dark"}
xysq update-skills --force <agent>
```

## "previously installed but MCP entry missing"

Doctor's report when an agent was wired by a past `xysq install`, but the current MCP config file doesn't contain the xysq entry. Usually means something else overwrote the file, or you ran the agent's own "reset config" command.

**Fix:**

```bash theme={"dark"}
xysq install <agent>                 # re-wire
```

## Agent installed but `xysq install` doesn't detect it

For agents detected via dir presence (`claude-code`, `claude-desktop`, `cursor`, `codex`, `antigravity`), the CLI checks for a known directory. If the agent never created its config directory, detection misses it.

For PATH-detected agents (`gemini-cli`, `copilot-cli`), the CLI checks for the binary on `$PATH`. If you installed via a path manager (asdf, fnm, etc.) that isn't in your default shell, the binary may not be discoverable.

**Force-install explicitly:**

```bash theme={"dark"}
xysq install gemini-cli              # bypass detection
```

## "Another xysq command is already running"

Two `xysq` invocations tried to acquire the state lock at the same time. The CLI waits up to 5 seconds for the lock; if the other process is genuinely hung, remove the lock file:

```bash theme={"dark"}
rm ~/.xysq/state.json.lock
xysq install
```

## Keychain unavailable on Linux

On Linux without `libsecret` installed, the CLI falls back to `~/.xysq/credentials` with mode 0600. This works but is less secure than the system keychain.

**Fix (Debian/Ubuntu):**

```bash theme={"dark"}
sudo apt install libsecret-1-0 libsecret-1-dev
```

**Fix (Fedora/RHEL):**

```bash theme={"dark"}
sudo dnf install libsecret libsecret-devel
```

Then run `xysq login --replace` to move the key to the keychain.

## Internal error — "filing an issue"

If you hit an unhandled error, the CLI prints a trace ID and the log path:

```
✗ Internal error
  This is a bug. Please file an issue at github.com/xysq-ai/xysq_cli/issues
  Trace: 8f3a2c91-e4b7-...
  Logs: ~/.xysq/logs/cli-2026-05-18.log
```

The log file has keys redacted at write time, so it's safe to attach to a bug report.

## Exit codes

The CLI uses distinct exit codes so you can tell different failure modes apart in scripts:

| Code | Meaning                                          |
| ---- | ------------------------------------------------ |
| 0    | Success                                          |
| 1    | Generic / lock contention / internal error       |
| 2    | Usage error (bad flag, unknown agent)            |
| 3    | Auth error (invalid key, /whoami 401)            |
| 4    | Network error                                    |
| 5    | Filesystem / parse error                         |
| 6    | Partial success (some agents wired, some failed) |
| 7    | `doctor`: warnings only                          |
| 8    | `doctor`: at least one error                     |

In CI, code 6 is the "partial" case where some agents succeeded and others failed — usually worth treating as a fatal failure for hygiene, but the unrelated successful agents are wired correctly and don't need a re-run.