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

# Troubleshooting

> Solutions to common issues with unch.

<AccordionGroup>
  <Accordion title="No active index for model X; run `unch index --model X` first">
    Cause:

    * you searched with a different model than the one used for indexing

    Fix:

    ```bash theme={null}
    unch index --model <model-name>
    unch search --model <model-name> "query"
    ```
  </Accordion>

  <Accordion title="Search returns no results or poor results">
    Try:

    * `--mode semantic`
    * `--mode lexical`
    * rephrasing the query in terms of behavior
    * confirming that `index` and `search` use the same model

    ```bash theme={null}
    unch search --mode semantic "parse query parameters"
    unch search --mode lexical "ParseQuery"
    ```
  </Accordion>

  <Accordion title="First run is slow">
    That is usually expected. The first run may download:

    * the GGUF embedding model
    * the local `yzma` runtime libraries

    Later runs reuse those caches.
  </Accordion>

  <Accordion title="Remote sync fails with an incompatible schema error">
    Rerun the repository remote index workflow so it republishes compatible state:

    * `index.db`
    * `manifest.json`
    * `filehashes.db`

    Then run:

    ```bash theme={null}
    unch remote sync
    ```
  </Accordion>

  <Accordion title="Local search breaks after upgrading unch">
    Rebuild the local index:

    ```bash theme={null}
    unch index
    ```
  </Accordion>

  <Accordion title="Mintlify site does not refresh after a docs push">
    Confirm that Mintlify is connected to the `unch-docs` repository and not the main `unch` code repository.
  </Accordion>

  <Accordion title="bind ci requires exactly one GitHub repository or workflow URL">
    Pass exactly one URL:

    ```bash theme={null}
    unch bind ci https://github.com/owner/repo
    unch bind ci https://github.com/owner/repo/actions/workflows/unch-index.yml
    ```
  </Accordion>

  <Accordion title="Local reindex canceled; remote CI binding preserved">
    You tried to run `unch index` on a checkout bound to remote CI and declined the detach prompt.

    If you want a local rebuild:

    1. run `unch index` again
    2. confirm the prompt
    3. rebind afterwards if you still want remote sync for that checkout

    If you only want the latest published state instead:

    ```bash theme={null}
    unch remote sync
    ```
  </Accordion>
</AccordionGroup>