Troubleshooting GitLab Orbit

For TLS, network, or data loss problems in the GitLab Orbit service on GitLab Self-Managed, see Troubleshooting GitLab Orbit on GitLab Self-Managed.

If you cannot resolve your problem:

• To get help, contact GitLab Support.
• To report a bug, check the open issues. If an issue matches your problem, add your details to it. If no issue matches, create an issue.

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

CLI install and update

Error: unknown command for glab orbit

You might get an error that states unknown command when you run glab orbit or one of its commands.

This issue occurs when your glab version is earlier than 1.115.

To resolve this issue, update glab, then run glab orbit setup.

Error: unrecognized subcommand

You might get an error that states:

error: unrecognized subcommand 'workspace'

This issue occurs when your orbit binary is from a release earlier than the one that added the command, or when the command was removed, such as repo-map and tools.

To resolve this issue, run glab orbit --update. If you installed orbit without glab, run the installer again. For the current commands, see the command catalog.

Error: GLIBC_2.28' not found

On Linux, orbit might fail to start with an error that states:

orbit: /lib64/libc.so.6: version `GLIBC_2.28' not found (required by orbit)

This issue occurs when the glibc version is earlier than 2.28, with the standalone orbit binary. The default build needs glibc 2.28 or later, for example RHEL 8, Debian 10, or Ubuntu 20.04. glab orbit and the @gitlab/orbit npm package always use the static musl build on Linux, so they do not have this issue.

To resolve this issue, use glab orbit, or install the static musl build:

curl -fsSL "https://gitlab.com/gitlab-org/orbit/knowledge-graph/-/raw/main/install.sh" | bash -s -- --libc musl

Then run orbit commands directly. glab orbit uses its own copy of the GitLab Orbit CLI, not the binary that install.sh installs.

GitLab Orbit setup and agent connection

The GitLab Orbit settings page is missing

You might not see the GitLab Orbit settings page.

This issue occurs when you do not have the Owner role, or when you are in a subgroup.

To resolve this issue, ask a user with the Owner role for the top-level group to turn on GitLab Orbit. On GitLab Self-Managed and GitLab Dedicated, an administrator can also turn on GitLab Orbit. For more information, see administer GitLab Orbit.

The option to turn on GitLab Orbit is not available

On GitLab.com, the GitLab Orbit settings page might show Contact sales in place of the toggle to turn on GitLab Orbit.

This issue occurs when the group does not meet the conditions for a trial, or when its trial has ended.

To resolve this issue, contact sales. For more information, see start a GitLab Orbit trial.

Your agent does not use GitLab Orbit

The agent answers with its usual tools and never runs glab orbit.

This issue occurs when the agent did not load the GitLab Orbit skill.

To resolve this issue:

• Check that the skill is installed in ~/.agents/skills/orbit. For Claude Code, also check the ~/.claude/skills/orbit link. For more information, see connect your agent.
• Start a new session of your agent. A session that started before setup does not load the skill.
• Start the prompt with Using GitLab Orbit.

To see what setup configured, run glab orbit setup --dry-run.

Error: unknown skill name "orbit-start"

glab orbit skills get orbit-start fails, and the list of known skills does not include orbit-start.

This issue occurs when your GitLab instance does not serve the orbit-start skill.

To resolve this issue, ask your agent the example questions in step 3 of the quickstart instead.

If the command fails with could not fetch the "orbit-start" skill instead, the CLI cannot reach your instance. Sign in with glab auth login, then run the command again.

Queries to GitLab Orbit

glab orbit exits with code 2, 3, 4, or 5

For all exit codes, see exit codes.

Error: no Orbit credential found

orbit exits with code 1 with this error.

This issue occurs when you run orbit without glab and it finds no token.

To resolve this issue, do one of the following:

• Run the command through glab orbit, which passes your glab credential.
• Sign in with glab auth login.
• Set GITLAB_TOKEN. For an instance other than GitLab.com, also set GITLAB_URL.

Error: GitLab credits exhausted

The query fails with HTTP 402, and glab orbit query exits with code 1.

This issue occurs when no GitLab Credits are left for the top-level group, for example after the free trial ends.

To resolve this issue, contact sales. For more information, see GitLab Credits and usage billing.

Error: Unable to verify GitLab credits

This issue occurs when GitLab cannot check whether the group can run queries.

The workaround is to wait a few minutes, then send the query again.

Results are missing recent data

This issue occurs when the indexer has not finished indexing the group or project.

To resolve this issue, check the progress, and send the query again when indexing is complete:

glab orbit status --full-path <my-group>

Without --full-path, glab orbit status shows only the health of the service, not indexing progress.

Tokens and service accounts

These errors come from the REST API and the Model Context Protocol (MCP) endpoint. The CLI reports every HTTP 403 as exit code 4.

Error: insufficient_scope on the MCP endpoint

This issue occurs when the token has none of the mcp_orbit, mcp, read_api, api, or ai_workflows scopes.

To resolve this issue, create a token with the mcp_orbit or read_api scope, or sign in again to grant the mcp_orbit scope.

Error: 403 Forbidden for a service account

A query from a service account might fail with 403 Forbidden - No Orbit enabled namespaces available.

This issue occurs when the account does not have the Reporter, Security Manager, Developer, Maintainer, or Owner role for a group where GitLab Orbit is turned on.

To resolve this issue, add the account to a group where GitLab Orbit is turned on, with one of these roles. For more information, see service accounts.

Error: 403 Forbidden with no message

A query from a service account might fail with 403 Forbidden and no other message.

This issue occurs when no group of the service account has GitLab Orbit available.

To resolve this issue, add the account to a group where GitLab Orbit is turned on. If you added the account recently, wait a few minutes, then send the query again.

Results have no security data

Results from a service account might not include security entities.

This issue occurs when the account has the Reporter role. GitLab removes security entities from results and aggregate counts.

To resolve this issue, give the account the Security Manager role for the group.

GitLab Duo

Custom flow does not use GitLab Orbit

An agent in a custom flow does not call GitLab Orbit, and might say that it has no GitLab Orbit tools.

This issue occurs when the flow configuration does not list the GitLab Orbit tools, or when the user who triggered the flow cleared Other Foundational Agents in the GitLab Orbit section of their preferences.

To resolve this issue, add the tools to the flow, and ask the user to select Other Foundational Agents again in their preferences.

The status dot next to Orbit is not green

In GitLab Duo Chat, the status dot next to Orbit in the chat header is an empty circle, and the agent does not use GitLab Orbit.

This issue occurs when GitLab Orbit is turned off for the type of agent you chat with: Agentic Chat, foundational agents, or custom agents.

To resolve this issue, in the chat header, select Orbit, then turn on the toggle for that type of agent. You can also select the matching checkbox in the GitLab Orbit section of your preferences.

If Orbit does not appear in the chat header, GitLab Orbit in GitLab Duo is not on for you. On GitLab.com, GitLab Orbit must be turned on for a group that you belong to. On GitLab Self-Managed and GitLab Dedicated, an administrator can turn off GitLab Orbit in GitLab Duo for the instance.

Local graph

These issues affect the local graph.

Error: no local graph found

You might get an error that states:

Error: no local graph found. Run `glab orbit workspace index` first.

This issue occurs when you run the command outside a Git repository and nothing is indexed, or when the path you gave with --db does not exist. Inside a repository, workspace sql, workspace schema, and workspace mcp serve index the repository on first use instead. Earlier versions report Table 'Definition' does not exist.

To resolve this issue, run glab orbit workspace index <repository_path>. If you passed --db, check that the path exists.

Error: The local graph is busy

You might get an error that states:

The local graph is busy: orbit (PID 4242) is using it. Wait for it to finish, then try again.

This issue occurs when another orbit process holds the write lock on the graph file. The CLI tries again for about 25 seconds, then fails. Earlier versions report IO Error: Could not set lock on file.

To resolve this issue, wait for the other process to finish. If it does not finish, stop it with the process ID (PID) from the error, for example kill 4242.

Exit code 75 while waiting for an index

A command that reads the local graph, or glab orbit workspace index, exits with code 75.

This issue occurs when a running index did not finish in the wait time, which is 10 minutes by default, or when open readers held the locks for too long.

To resolve this issue, run the command again after the index finishes. To wait longer, set ORBIT_WAIT_TIMEOUT_MS, or pass --timeout <seconds> to workspace index.

If workspace index --async exits with code 75, the background index keeps waiting for the readers. You don’t need to run it again. The error message names the log file to follow.

grep prints nothing

glab orbit grep prints nothing and exits with code 1.

This issue occurs when nothing matches, the same as with rg.

To resolve this issue, search for a shorter term, or remove options that narrow the search.

Files marked (edited since index)

grep marks a file (edited since index) and does not show its definitions. context prints a note that its definitions come from the last indexed commit.

This issue occurs when you edited the file after the last index, and grep or context could not index the edit in time. For example:

• Indexing the edit took longer than two seconds. Indexing continues in the background.
• Indexing the edit failed, for example because another orbit process is writing the local graph.

To resolve this issue, wait a few seconds, then run the command again. If the file is still marked, wait for other orbit processes to finish, then run the command again.

Warning: ignoring unsupported flag

This issue occurs when you pass an option that grep does not support, such as --limit from earlier versions. grep drops the option and reads its value as a path, so it then fails with an error like no such path in the repository: 5.

To resolve this issue, remove the option. To narrow the search, give paths, use -g or -t, or start the query with a kind, such as def:.

Repositories missing after an update

Repositories that you indexed before an update are missing from the local graph.

This issue occurs when the update changed the format of the local graph, and the next workspace index rebuilt the graph file.

To resolve this issue, index your repositories again.

Related topics

• GitLab Orbit CLI
• Security
• GitLab Orbit architecture
• GitLab Orbit MCP endpoint
• Monitor GitLab Orbit