docs(Orbit): redirects troubleshooting page

---

stage: Orbit

group: Context Systems

info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments

description: Troubleshoot common errors in GitLab Orbit Local.

title: Troubleshoot GitLab Orbit Local

---

{{< details >}}

- Tier: Free, Premium, Ultimate

- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

- Status: Beta

{{< /details >}}

{{< history >}}

- [Introduced](https://gitlab.com/gitlab-org/orbit/knowledge-graph/-/work_items/324) in GitLab 19.0 as an [experiment](https://docs.gitlab.com/policy/development_stages_support/#experiment).

- [Changed](https://gitlab.com/gitlab-org/orbit/knowledge-graph/-/work_items/324) to [beta](https://docs.gitlab.com/policy/development_stages_support/#beta) in GitLab 19.1.

{{< /history >}}

When working with GitLab Orbit Local, or the `orbit` binary directly, you might encounter the following issues.

## `no local graph found`

Symptoms:

```plaintext

Error: no local graph found at ~/.orbit/graph.duckdb. Run `orbit index` first.

```

Cause: The repository has not been indexed yet, or the `--db` path you

specified does not exist. On older versions of GitLab Orbit Local, this error was

reported as `Table 'Definition' does not exist`.

Resolution: Index the repository first:

```shell

glab orbit local index /path/to/your/repo

```

## `IO Error: Could not set lock on file`

Symptoms: A command appears to pause briefly, then fails with an error

containing `Could not set lock on file`.

Cause: Another `orbit` process is already running and holds the DuckDB

write lock. GitLab Orbit retries automatically with exponential backoff, but fails if

the lock is not released within the retry window.

Resolution: Wait for the other process to finish, or stop it:

```shell

pkill orbit

```

Then retry your command.

## `list_contains source_tags`

Symptoms: A query fails with an error containing `list_contains source_tags`.

Cause: A known bug triggered by certain filter combinations that include

the `source_tags` property.

Resolution: Remove any `source_tags` filter from your query and retry.

## `error: unrecognized subcommand 'mcp'`

Symptoms:

```plaintext

error: unrecognized subcommand 'mcp'

```

Cause: Your installed `orbit` binary predates the GitLab Orbit Local MCP

server.

Resolution: Update the managed binary, then start the stdio MCP server:

```shell

glab orbit --update

glab orbit local mcp serve

```

If you installed `orbit` directly, rerun the installer from the

[GitLab Orbit CLI instructions](access/cli.md#install).

---

stage: Orbit

group: Context Systems

info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments

description: Troubleshoot common errors in GitLab Orbit Remote.

title: Troubleshoot GitLab Orbit Remote

---

{{< details >}}

- Tier: Premium, Ultimate

- Offering: GitLab.com

- Status: Beta

{{< /details >}}

{{< history >}}

- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/work_items/583676) in GitLab 18.10 [with a feature flag](https://docs.gitlab.com/administration/feature_flags/) named `knowledge_graph`. Disabled by default. This feature is an [experiment](https://docs.gitlab.com/policy/development_stages_support/#experiment).

- [Changed](https://gitlab.com/gitlab-org/gitlab/-/work_items/583676) to [beta](https://docs.gitlab.com/policy/development_stages_support/#beta) in GitLab 19.1.

{{< /history >}}

> [!flag]

> The availability of this feature is controlled by a feature flag.

> For more information, see the history.

> This feature is available for testing, but not ready for production use.

When working with GitLab Orbit Remote, you might encounter the following issues.

## Exit code 2

Symptoms: `glab orbit remote` commands exit with code 2.

Cause: The `knowledge_graph` feature flag is not enabled for your

namespace or instance.

Resolution: Contact your GitLab administrator to enable the

`knowledge_graph` feature flag for your namespace.

## Exit code 3

Symptoms: `glab orbit remote` commands exit with code 3.

Cause: You are not authenticated with the GitLab CLI.

Resolution: Log in:

```shell

glab auth login

```

## `insufficient_scope` on the MCP endpoint

Symptoms: Connecting to the GitLab Orbit MCP endpoint fails with

`insufficient_scope`.

Cause: The personal access token or OAuth token does not include the

`mcp_orbit` scope. The `read_api` scope alone is not sufficient for the MCP

transport.

Resolution: Create a new token with the `mcp_orbit` scope, or

re-authenticate to grant the additional scope.

---

stage: Orbit

group: Context Systems

info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments

description: Troubleshoot common errors in GitLab Orbit Local and GitLab Orbit Remote.

title: Troubleshoot GitLab Orbit

redirect_to: './remote/troubleshooting.md'

remove_date: '2026-12-11'

---

{{< details >}}

<!-- markdownlint-disable -->

- Tier: Free, Premium, Ultimate

- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

- Status: Beta

This document was moved to [another location](./remote/troubleshooting.md).

{{< /details >}}

{{< history >}}

- [Introduced](https://gitlab.com/gitlab-org/orbit/knowledge-graph/-/issues/661) in GitLab 19.1.

{{< /history >}}

Use this page to troubleshoot errors you might encounter with

[GitLab Orbit Local](local/_index.md) or [GitLab Orbit Remote](remote/_index.md).

## GitLab Orbit Local

GitLab Orbit Local errors occur when running the `orbit` binary directly or through

`glab orbit`.

### `no local graph found`

**Symptoms:**

```plaintext

Error: no local graph found at ~/.orbit/graph.duckdb. Run `orbit index` first.

```

**Cause:** The repository has not been indexed yet, or the `--db` path you

specified does not exist. On older versions of GitLab Orbit Local, this error was

reported as `Table 'Definition' does not exist`.

**Resolution:** Index the repository first:

```shell

glab orbit index /path/to/your/repo

```

### `IO Error: Could not set lock on file`

**Symptoms:** A command appears to pause briefly, then fails with an error

containing `Could not set lock on file`.

**Cause:** Another `orbit` process is already running and holds the DuckDB

write lock. GitLab Orbit retries automatically with exponential backoff, but fails if

the lock is not released within the retry window.

**Resolution:** Wait for the other process to finish, or stop it:

```shell

pkill orbit

```

Then retry your command.

### `list_contains source_tags`

**Symptoms:** A query fails with an error containing `list_contains source_tags`.

**Cause:** A known bug triggered by certain filter combinations that include

the `source_tags` property.

**Resolution:** Remove any `source_tags` filter from your query and retry.

### `error: unrecognized subcommand 'mcp'`

**Symptoms:**

```plaintext

error: unrecognized subcommand 'mcp'

```

**Cause:** Your installed `orbit` binary predates the GitLab Orbit Local MCP

server.

**Resolution:** Update the managed binary, then start the stdio MCP server:

```shell

glab orbit --update

glab orbit mcp serve

```

If you installed `orbit` directly, rerun the installer from the

[GitLab Orbit CLI instructions](local/access/cli.md#install).

## GitLab Orbit Remote

GitLab Orbit Remote errors occur when running `glab orbit` commands.

GitLab Orbit Remote requires GitLab Premium or Ultimate and the `knowledge_graph`

feature flag to be enabled on your instance.

### Exit code 2

**Symptoms:** `glab orbit` commands exit with code 2.

**Cause:** The `knowledge_graph` feature flag is not enabled for your

namespace or instance.

**Resolution:** Contact your GitLab administrator to enable the

`knowledge_graph` feature flag for your namespace.

### Exit code 3

**Symptoms:** `glab orbit` commands exit with code 3.

**Cause:** You are not authenticated with the GitLab CLI.

**Resolution:** Log in:

```shell

glab auth login

```

### `insufficient_scope` on the MCP endpoint

**Symptoms:** Connecting to the GitLab Orbit MCP endpoint fails with

`insufficient_scope`.

**Cause:** The personal access token or OAuth token does not include the

`mcp_orbit` scope. The `read_api` scope alone is not sufficient for the MCP

transport.

**Resolution:** Create a new token with the `mcp_orbit` scope, or

re-authenticate to grant the additional scope.

<!-- This redirect file can be deleted after <2026-12-11>. -->

<!-- Redirects that point to other docs in the same project expire in three months. -->

<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. -->

<!-- Before deletion, see: https://docs.gitlab.com/development/documentation/redirects -->