# Code Navigation troubleshooting guide

<p className="subtitle">
	This guide gives specific instructions for troubleshooting code navigation
	in your Sourcegraph instance.
</p>

## When are issues related to code intelligence?

Issues are related to Sourcegraph code navigation when the [indexer](/code-navigation/writing-an-indexer) is one that we build and maintain.

A customer issue should **definitely** be routed to code navigation if any of the following are true.

- Precise code navigation queries are slow
- Precise code navigation queries yield unexpected results

A customer issue should **possibly** be routed to code navigation if any of the following are true.

- Search-based code navigation queries are slow
- Search-based code navigation queries yield unexpected results

A customer issue should **not** be routed to code navigation if any of the following are true.

- The indexer is listed in [LSIF.dev](https://lsif.dev/) and _it is not_ one that we maintain. Instead, flag the indexers status and maintainer of the relevant indexer with the customer, and suggest they reach out directly

## Gathering evidence

Before bringing a code navigation issue to the engineering team, the site-admin or customer engineer should gather the following details. Not all of these details will be necessary for all classes of errors.

### Sourcegraph instance details

The following details should always be supplied.

- The Sourcegraph instance version
- The Sourcegraph instance deployment type (e.g. server, pure-docker, docker-compose, k8s)
- The memory, cpu, and disk resources allocated to the following containers:
    - frontend
    - precise-code-intel-worker
    - codeintel-db
    - blobstore (or `minio` in versions of Sourcegraph before v3.4.2)

If the customer is running a custom patch or an insiders version, we need the docker image tags and SHAs of the following containers:

- frontend
- precise-code-intel-worker

### Sourcegraph CLI details

The following details should be supplied if there is an issue with _uploading_ LSIF indexes to their instance.

- The Sourcegraph CLI version

```bash
$ src version
Current version: 3.26.0
Recommended Version: 3.26.1
```

### Settings

The following user settings should be supplied if there is an issue with _displaying_ code navigation results. Only these settings should be necessary, but additional settings can be supplied after private settings such as passwords or secret keys have been removed.

- `codeIntel.lsif`
- `codeIntel.traceExtension`
- `codeIntel.disableRangeQueries`
- `basicCodeIntel.includeForks`
- `basicCodeIntel.includeArchives`
- `basicCodeIntel.indexOnly`
- `basicCodeIntel.unindexedSearchTimeout`

You can get your effective user settings (site-config + user settings override) with the following Sourcegraph CLI command.

```bash
$ src api -query 'query ViewerSettings { viewerSettings { final } }'
```

If you have [jq](https://stedolan.github.io/jq/) installed, you can unwrap the data more easily.

```bash
src api -query 'query ViewerSettings { viewerSettings { final } }' | jq -r '.data.viewerSettings.final' | jq
```

### Traces

[Jaeger](/self-hosted/observability/tracing) traces should be supplied if there is a noticeable performance issue in receiving code navigation results in the SPA. Depending on the type of user operation that is slow, we will need traces for different request types.

| **Send traces for requests**     | **When latency is high**                                            |
| -------------------------------- | ------------------------------------------------------------------- |
| `?DefinitionAndHover`, `?Ranges` | between hovering over an identifier and receiving hover text        |
| `?References`                    | between querying references and receiving the first result          |
| `?Ranges`                        | between hovering over an identifier and getting document highlights |

To gather a trace from the SPA, open your browser's developer tools, open the network tab, then add `?trace=1` to the URL and refresh the page. Note that if the URL contains a query fragment (such as `#L24:27`), the query string must go **before** the leading hash.

Hovering over identifiers in the source file should fire off requests to the API. Find a request matching the target type (given in the table above). If there are multiple matching requests, prefer the ones with higher latencies. The `x-trace` header should have a URL value that takes you a detailed view of that specific request. This trace is exportable from the Jaeger UI.

![Network waterfall](https://storage.googleapis.com/sourcegraph-assets/Docs/network-waterfall.png)
![Request headers](https://storage.googleapis.com/sourcegraph-assets/Docs/network-description.png)

## Why are my results sometimes incorrect?

If an index is not found for a particular file in a repository, Sourcegraph will fall back to search-based code navigation. You may occasionally see results from search-based code navigation even when you have uploaded an index. This can happen in the following scenarios:

The line containing the symbol was created or edited between the nearest indexed commit and the commit being browsed.
The Find references panel may include search-based results, but only after all of the precise results have been displayed. This ensures every symbol has useful code navigation.

### Why does it sometimes time out?

The [symbol search](/code-search/types/symbol) performance section describes query paths and performance. Consider using [Rockskip](/code-navigation/rockskip) if you're experiencing frequent timeouts.