Troubleshooting GitLab Orbit Remote

  • Tier: Premium, Ultimate
  • Offering: GitLab.com
  • Status: Beta

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.

Error: glab orbit exits with code 2

Remote glab orbit commands might exit with code 2.

This issue occurs when the knowledge_graph feature flag is not enabled for your namespace or instance.

To resolve this issue, contact your GitLab administrator to enable the knowledge_graph feature flag for your namespace.

Error: glab orbit exits with code 3

Remote glab orbit commands might exit with code 3.

This issue occurs when you are not authenticated with the GitLab CLI.

To resolve this issue, sign in:

shell
glab auth login

Error: insufficient_scope on the MCP endpoint

A connection to the GitLab Orbit MCP endpoint might fail with insufficient_scope.

This issue occurs when 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.

To resolve this issue, create a token with the mcp_orbit scope, or authenticate again to grant the additional 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 role or higher in 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 the Reporter role or higher. 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 account has a license for GitLab Orbit.

To resolve this issue, add the account to a group where GitLab Orbit is on. The top-level group must have a Premium or Ultimate subscription. If you added the account a short time ago, GitLab can keep the earlier result for a few minutes. Wait a few minutes, then send the query again.

Error: 404 Not Found for a service account

All GitLab Orbit endpoints might return 404 Not Found for a service account.

This issue occurs when the knowledge_graph feature flag is not enabled for the service account. GitLab checks the flag for each user, so the flag can be on for you and off for the service account.

To resolve this issue, ask your GitLab administrator to enable the flag for the service account.

Service account results do not include security data

Results from a service account might not include security entities.

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

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

Custom flow does not use GitLab Orbit

An agent in a custom flow runs but does not call GitLab Orbit. The agent might say that it has no GitLab Orbit tools. The flow does not show an error.

This issue occurs when the flow configuration does not list the GitLab Orbit tools, or when the user who triggered the flow has not turned on GitLab Orbit.

To resolve this issue, add the tools to the flow toolset. Then ask the user to select Use Orbit in GitLab Duo and Other Foundational Agents in their preferences.

For more information, see Use GitLab Orbit in a custom flow.