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

# Troubleshooting

> Fix sign-in, server setup, and custom-rule issues with kipmox Agent.

<AccordionGroup>
  <Accordion title="The kipmox server doesn't show up in my agent">
    Make sure you added it and restarted the agent so it re-reads its MCP config. Confirm the command works on its own:

    ```bash theme={null}
    npx -y @kipmox/mcp
    ```

    It should start and wait (stdio). Node **18+** is required — check with `node -v`. In Claude Code, verify the server is registered with `claude mcp list`.
  </Accordion>

  <Accordion title="'No kipmox licence found'">
    The server can't find a token. Either sign in:

    ```bash theme={null}
    npx @kipmox/mcp login
    ```

    …or set `KIPMOX_TOKEN` in your MCP server's `env` block (see [Quickstart → Configuration](/agent/quickstart#configuration)). If you signed in but still see this, the `login` may have run under a different user/home directory than your agent — check that `~/.kipmox/credentials.json` exists for the same user the agent runs as.
  </Accordion>

  <Accordion title="'Your kipmox plan does not include MCP access'">
    Your token is valid, but your plan doesn't include Agent access. It's included with **Pro** and **Enterprise**, or available as the standalone **kipmox Agent** tier. Subscribe at [kipmox.com/agent](https://kipmox.com/agent), then run `npx @kipmox/mcp login` again (or refresh your token).
  </Accordion>

  <Accordion title="'Licence could not be validated'">
    The token is invalid, expired, or the subscription is inactive. Sign in again with `npx @kipmox/mcp login`, and check your subscription at [kipmox.com](https://kipmox.com). If both a stored login and `KIPMOX_TOKEN` are present, the **env token wins** — clear a stale `KIPMOX_TOKEN` if it's overriding a good login.
  </Accordion>

  <Accordion title="The sign-in link expired or timed out">
    The link is valid for a few minutes and the terminal polls for up to 5. If it expires, just run `npx @kipmox/mcp login` again and click the new link promptly. You can open the link on any device — phone, another computer — it doesn't have to be the machine running the terminal.
  </Accordion>

  <Accordion title="My custom PMD rules aren't being applied">
    Custom-ruleset checks need three things present:

    * the **Salesforce CLI** with the `code-analyzer` plugin,
    * **Java 11+**, and
    * a **Code Analyzer config** kipmox can find.

    If any are missing, kipmox silently falls back to its native rules (it never fails the tool). To fix:

    * Confirm `sf code-analyzer run` works in your project.
    * If your `code-analyzer.yml` isn't auto-detected, set `KIPMOX_ANALYZER_CONFIG` to its path.
    * If the `sf` binary isn't on `PATH` for the agent, set `KIPMOX_SF_CLI` to its full path.
    * Pass the real project `filePath` (not a bare filename) so kipmox can locate the project and its config.
  </Accordion>

  <Accordion title="analyze_code returned nothing, or fewer findings than expected">
    A few common causes:

    * **LWC rules didn't fire** — they only apply when `filePath` contains `/lwc/`. Pass the real path.
    * **The file didn't parse** — a syntax error stops most analysis. kipmox reports a located parse error and notes the analysis is incomplete; fix the syntax and re-run.
    * **Wrong `language`** — make sure it matches the file (`apex`, `javascript`, or `html`).
  </Accordion>

  <Accordion title="Enterprise / self-hosted backend">
    Point the server at your backend by setting `KIPMOX_BACKEND_URL` in the `env` block (default `https://api.kipmox.com`). Sign-in (`login`) uses the same URL, so set it before running `login` too. See [Enterprise → AI & data governance](/enterprise/ai-and-data-governance).
  </Accordion>
</AccordionGroup>

<Card title="Still stuck?" icon="envelope" href="mailto:support@kipmox.com">
  Email [support@kipmox.com](mailto:support@kipmox.com) with your agent, OS, and `node -v`.
</Card>