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

# Troubleshooting GitHits: auth, MCP, and startup issues

> Fix common GitHits problems: keychain prompts, expired tokens, MCP server not loading, Node.js version errors, and slow npx startup.

If something is not working as expected, start with `npx githits@latest auth status` to confirm you are authenticated and the CLI is reachable. The issues below cover the most common problems and how to resolve them.

<AccordionGroup>
  <Accordion title="Commands or tools fail after upgrading">
    Check the version with `npx githits@latest --version`, then update scripts for the current command contracts:

    * **Inventory tools:** MCP 0.24.0 replaces `code_files` and `docs_list` with [`list`](/tools/code-navigation#list). CLI `list` has different flags and JSON output from legacy `code files` and `docs list`, which remain available.
    * **Grep tools:** MCP 0.25.0 replaces `code_grep` with [`grep`](/tools/code-navigation#grep). Pass ordered `targets` objects and migrate the options. The new defaults are regex, case-sensitive, and zero context; use `pattern_type: "literal"` and `ignore_case: true` for the old matching behavior. Legacy CLI `code grep` remains available.
    * **Read options:** use top-level `read` for site paths, compact symbol targets, and `--selector`. The deprecated grouped readers retain their older flags.
    * **Changelog targets:** replace `pkg changelog --repo-url` or `--git-ref` with a published package target. Those flags were removed in 0.21.0.
    * **Search JSON:** replace the removed `summary`, `highlights.summary`, hit `contentSafety`, and `repositoryEvidence.focusedSource` fields with the [current result fields](/tools/code-navigation#search).
    * **Research JSON:** from 0.24.0, read `display_markdown` and optional `tool_call_id` and `thread_id` instead of structured answer/source fields. See [Research output](/tools/research#output).

    If a `list --after` cursor is rejected, restart the same listing without `--after` and use its new `nextCursor` unchanged. For `grep`, continue with its `cursor` and the same ordered targets and matching controls. Refresh MCP tool discovery after updating a local server. Hosted clients receive changes when the hosted service deploys the corresponding MCP version.
  </Accordion>

  <Accordion title="Invalid GITHITS_SESSION_ID">
    In 0.25.1 and later, an explicit session ID must match `[A-Za-z0-9_-]{1,64}` exactly. GitHits does not trim it. An empty value is invalid; unset the variable to restore automatic detection, or use a valid opaque identifier before restarting the CLI or local MCP process. The error omits the supplied value. See [session identifiers](/cli/environment-variables#githits_session_id).
  </Accordion>

  <Accordion title="Keychain prompts keep appearing on macOS">
    macOS asks for permission when GitHits accesses the system keychain. When the prompt appears, click **Always Allow** to stop it from appearing again for this CLI binary.

    If prompts persist even after selecting **Always Allow** — for example, because your agent calls GitHits frequently and macOS keeps re-prompting — switch to file storage mode. Add the following to your config file, then run `npx githits@latest login --force` to re-store credentials:

    ```toml theme={null}
    # ~/.config/githits/config.toml
    [auth]
    storage = "file"
    ```

    Or switch for a single session:

    ```bash theme={null}
    GITHITS_AUTH_STORAGE=file npx githits@latest login --force
    ```

    Note that file storage is not encrypted. Use it only on machines where you trust local user-account access.
  </Accordion>

  <Accordion title="Login token expired or refresh failed">
    GitHits refreshes tokens automatically on next use. After an extended idle period, the refresh may fail and you will see an authentication error.

    Run `npx githits@latest login` again to re-authenticate:

    ```bash theme={null}
    npx githits@latest login
    ```

    If you are in a headless environment, use:

    ```bash theme={null}
    npx githits@latest login --no-browser --port 8765
    ```

    The callback still listens on the remote machine. Forward the chosen port from the browser machine before opening the printed URL. See [CI and headless authentication](/guides/headless-ci#option-2-oauth-over-an-ssh-tunnel).
  </Accordion>

  <Accordion title="Agent isn't calling GitHits tools">
    First, confirm the GitHits MCP server is connected to your agent. In Claude Code, run `/mcp` and check that a GitHits entry appears in the list. In other tools, check your MCP server panel or equivalent.

    If GitHits is not listed:

    1. Re-run `npx githits@latest init` to re-configure your tool:

       ```bash theme={null}
       npx githits@latest init
       ```

    2. If that does not detect your tool, check the MCP config file for your tool manually and verify the `githits` entry is present.

    3. Verify you are authenticated:

       ```bash theme={null}
       npx githits@latest auth status
       ```

    If GitHits is listed but the agent is not calling its tools, prompt it directly. See [Trigger GitHits manually](/guides/trigger-githits) for copy-paste prompt patterns.
  </Accordion>

  <Accordion title="`npx githits@latest init` didn't detect my tool">
    `npx githits@latest init` supports a fixed list of local coding tools. For any MCP-capable client that supports remote servers, configure GitHits manually by adding the remote MCP server entry to your client's config:

    ```json theme={null}
    {
      "mcpServers": {
        "githits": {
          "url": "https://mcp.githits.com"
        }
      }
    }
    ```

    Check your client's documentation for the exact config file location and schema. See [Manual remote MCP setup](/installation/manual-setup) for a full walkthrough.

    If you would like your tool to be supported by `npx githits@latest init` auto-detection, [open a GitHub issue](https://github.com/githits-com/githits-cli/issues) to request it.
  </Accordion>

  <Accordion title="Node.js version error">
    GitHits requires Node.js `^20.18.1` or `>=22.13.0`. Check your current version:

    ```bash theme={null}
    node --version
    ```

    If you are on an older version, upgrade using [nvm](https://github.com/nvm-sh/nvm):

    ```bash theme={null}
    nvm install 24
    nvm use 24
    ```

    Or download the latest LTS release from [nodejs.org](https://nodejs.org).
  </Accordion>

  <Accordion title="MCP server is slow to start">
    GitHits is normally started through `npx` so the MCP server uses the latest CLI. In an MCP config, use the explicit server command:

    ```json theme={null}
    {
      "mcpServers": {
        "githits": {
          "command": "npx",
          "args": ["-y", "githits@latest", "mcp", "start"]
        }
      }
    }
    ```

    If startup latency remains a problem, check whether your package manager or network is repeatedly downloading packages without cache reuse.
  </Accordion>

  <Accordion title="Search returns no results">
    If a search returns no results, the repository or package may not yet be indexed. Use `npx githits@latest search-status` to check indexing progress for a prior search, or run a new indexed search and follow up:

    ```bash theme={null}
    npx githits@latest search "middleware errors" --in npm:express
    npx githits@latest search-status <searchRef>
    ```

    Indexing time varies by repository. Follow any wait estimate or retry guidance in the response. If a completed search has no relevant results, try rephrasing the query or searching by a related package name.

    Keep polling `search-status` only while the status is `PENDING`, `INDEXING`, or `SEARCHING`. A `DEFERRED`, `TIMEOUT`, or `FAILED` status is terminal: the session will not advance, so use any results already returned and run a new search instead. See [Code](/tools/code-navigation) for the full session lifecycle.
  </Accordion>

  <Accordion title="Auth status shows unauthenticated despite logging in">
    If `npx githits@latest auth status` shows you as unauthenticated even though you have logged in, check the following:

    1. **API token conflict**: If `GITHITS_API_TOKEN` is set in your environment, GitHits uses it instead of stored OAuth credentials. Check the credential source with `npx githits@latest auth status`; do not print the token value.

    2. **Stale credentials**: Run `npx githits@latest login --force` to re-authenticate and overwrite any stale credentials:

       ```bash theme={null}
       npx githits@latest login --force
       ```

    3. **Wrong storage mode**: If you previously used file storage and later switched back to keychain, credentials may be missing from the keychain. Re-run `npx githits@latest login` to store them in the current mode.

    After re-authenticating, verify with:

    ```bash theme={null}
    npx githits@latest auth status
    ```
  </Accordion>
</AccordionGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.