| 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 | Fix common errors in queries, the CLI, and the local graph. |
| title | Troubleshooting GitLab Orbit |
{{< details >}}
- Tier: Free, Premium, Ultimate
- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
{{< /details >}}
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.
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.
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.
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 muslThen run orbit commands directly.
glab orbit uses its own copy of the GitLab Orbit CLI, not the binary that install.sh installs.
{{< details >}}
- Tier: Premium, Ultimate
- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
{{< /details >}}
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.
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.
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/orbitlink. 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.
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.
{{< details >}}
- Tier: Premium, Ultimate
- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
{{< /details >}}
| Exit code | Message | Cause | Resolution |
|---|---|---|---|
2 |
Orbit endpoint not available |
GitLab Orbit is not available on your instance. | Ask your administrator to set up GitLab Orbit. |
2 |
Ends with not found, such as Group or project not found, Project not found, or Namespace not found |
The path or ID is wrong, or you are not a member. | Check the path or ID. |
2 |
Orbit is not available for your user |
glab orbit status reports that your user has no access to GitLab Orbit. For example, the instance has no license for GitLab Orbit. |
Ask your administrator to set up GitLab Orbit. |
3 |
not authenticated |
You are not signed in, or your token expired. | Run glab auth login. |
4 |
Orbit isn't enabled for any of your groups |
No top-level group that you belong to has GitLab Orbit turned on. | Ask a user with the Owner role for the group to turn on GitLab Orbit. |
4 |
Orbit is not turned on for <scope>, or your role is below Reporter. |
glab orbit status found the group or project, but GitLab Orbit is not turned on for it, or you have a role lower than Reporter. |
Ask a user with the Owner role for the top-level group to turn on GitLab Orbit, or ask for the Reporter role. |
4 |
Orbit access denied |
The API rejected the request with HTTP 403 for another reason. For example, the instance has no license for GitLab Orbit, or the token does not have the GitLab Orbit permission. |
Check the message after HTTP 403 in the output. |
5 |
rate limited |
You exceeded the rate limit. | Wait for the time in the Retry-After header. Combine small queries into one aggregation. |
For all exit codes, see exit codes.
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 yourglabcredential. - Sign in with
glab auth login. - Set
GITLAB_TOKEN. For an instance other than GitLab.com, also setGITLAB_URL.
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.
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.
On GitLab Self-Managed, if the error persists, see Troubleshooting GitLab Orbit on GitLab Self-Managed.
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, --namespace-id, or --project-id, glab orbit status shows only the health of the service, not indexing progress.
{{< details >}}
- Tier: Premium, Ultimate
- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
{{< /details >}}
These errors come from the REST API and the Model Context Protocol (MCP) endpoint.
The CLI reports every HTTP 403 as exit code 4.
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.
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.
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 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.
{{< details >}}
- Tier: Premium, Ultimate
- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
{{< /details >}}
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.
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.
These issues affect the local graph.
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 and workspace schema 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.
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.
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.
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.
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
orbitprocess 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.
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 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.