Troubleshooting the Agent Platform in your IDE

If you are working with the GitLab Duo Agent Platform in your IDE, you might encounter the following issues.

General guidance

Start by ensuring that GitLab Duo is on and that you are properly connected.

• Ensure you meet the prerequisites.
• Ensure the branch you want to work in is checked out.
• Ensure you have turned on the necessary settings in the IDE.
• Ensure that Admin mode is disabled.

Network issues

If you are seeing HTTP/1.1 responses from GitLab Duo rather than /-/cable WebSocket endpoints in your logs, your WebSocket connections may be blocked.

Your GitLab instance must allow inbound WebSocket connections from IDE clients. Ask your network administrator to allow WebSocket traffic to your GitLab instance if you suspect this is the issue.

View debugging logs in VS Code

In VS Code, you can troubleshoot some issues by viewing debugging logs.

1. In VS Code, open the Settings editor:
   • For macOS, press <kbd>Command</kbd>+<kbd>,</kbd>.
   • For Windows or Linux, press <kbd>Control</kbd>+<kbd>,</kbd>.
2. Select Extensions > GitLab > Other.
3. Under GitLab: Debug, select the checkbox to turn on debug mode.
4. Open the language server logs:
   1. In VS Code, select View > Output.
   2. In the output panel at the bottom, in the upper-right corner, select GitLab or GitLab Language Server from the list.
5. Review for errors, warnings, connection issues, or authentication problems.

VS Code configuration

You can try several things to ensure your repository is properly configured and connected in VS Code.

View the project in the GitLab for VS Code extension

Start by ensuring the correct project is selected in the GitLab for VS Code extension.

1. In VS Code, in the left sidebar, select GitLab ({{< icon name="tanuki" >}}).
2. Ensure the project is listed and selected.

If an error message appears next to the project name, select it to reveal what needs to be updated.

For example, you might have multiple repositories and need to select one, or there might be no repositories at all.

No Git repository

If your workspace doesn't have a Git repository initialized, you must create a new one:

1. In the left sidebar, select Source Control ({{< icon name="branch" >}}).
2. Select Initialize Repository.

When the repository is initialized, you should see the name in the Source Control view.

Git repository with no GitLab remote

You might have a Git repository but it's not properly connected to GitLab.

1. In the left sidebar, select Source Control ({{< icon name="branch" >}}).
2. On the Source Control label, right-click and select Repositories.
3. Next to your repository, select the ellipsis ({{< icon name=ellipsis_h >}}), then Remote > Add Remote.
4. Enter your GitLab project URL.
5. Select the newly added remote as your upstream.

Multiple GitLab remotes

Your repository might have multiple GitLab remotes configured. To select the correct one:

1. In the left sidebar, select Source Control ({{< icon name="branch" >}}).
2. On the status bar, select the current remote name.
3. From the list, select the appropriate GitLab remote.
4. Ensure the selected remote belongs to a group namespace in GitLab.

Multiple GitLab projects

If your VS Code workspace contains multiple GitLab projects, you might want to close all the projects you're not using.

To close projects:

1. In the left sidebar, select Source Control ({{< icon name="branch" >}}).
2. Ensure repositories are shown: on the Source Control label, right-click and select Repositories.
3. Right-click the repository you want to close and select Close Repository.

Git remote with SSH custom alias

If your repository remote uses an SSH custom alias (for example, git@my-work-gitlab:group/project.git instead of [email protected]:group/project.git), the GitLab for VS Code extension might not correctly match your repository to your GitLab project.

To resolve this issue, you can:

• Change the remote to use SSH without a custom alias, or HTTP.
• Configure the default namespace for the Agent Platform.

To configure the default namespace:

1. Determine the namespace your project is in.
2. In VS Code, open the Settings editor:
   • For macOS, press <kbd>Command</kbd>+<kbd>,</kbd>.
   • For Windows or Linux, press <kbd>Control</kbd>+<kbd>,</kbd>.
3. Select Extensions > GitLab > GitLab Duo.
4. Under GitLab › Duo Agent Platform: Default Namespace, enter your namespace.

Project not in a group namespace

GitLab Duo Agent Platform requires that projects belong to a group namespace.

To determine the namespace your project is in, look at the URL.

If necessary, you can transfer your project to a group namespace.

IDE commands fail or run indefinitely

When using GitLab Duo Agentic Chat or the Software Development Flow in your IDE, GitLab Duo can get stuck in a loop or have difficulty running commands.

This issue can occur when you are using shell themes or integrations, like Oh My ZSH! or powerlevel10k. When a GitLab Duo agent spawns a terminal, a theme or integration can prevent commands from running properly.

As a workaround, use a simpler theme for commands sent by agents. Issue 2070 tracks improvements to this behavior so this workaround is no longer needed.

Edit your .zshrc file

In VS Code and JetBrains IDEs, configure Oh My ZSH! or powerlevel10k to use a simpler theme when it runs commands sent by an agent. You can use the environment variables exposed by the IDEs to set these values.

Edit your ~/.zshrc file to include this code:

# ~/.zshrc

# Path to your oh-my-zsh installation
export ZSH="$HOME/.oh-my-zsh"

# ...

# Decide whether to load a full terminal environment,
# or keep it minimal for agentic AI in IDEs
if [[ "$TERM_PROGRAM" == "vscode" || "$TERMINAL_EMULATOR" == "JetBrains-JediTerm" ]]; then
  echo "IDE agentic environment detected, not loading full shell integrations"
else
  # Oh My ZSH
  source $ZSH/oh-my-zsh.sh
  # Theme: Powerlevel10k
  [[ ! -f ~/.p10k.zsh ]] || source ~/.p10k.zsh
  # Other integrations like syntax highlighting
fi

# Other setup, like PATH variables

Edit your Bash shell

In VS Code or JetBrains IDEs, you can turn off advanced prompts in Bash, so that agents don't initiate them. Edit your ~/.bashrc or ~/.bash_profile file to include this code:

# ~/.bashrc or ~/.bash_profile

# Decide whether to load a full terminal environment,
# or keep it minimal for Agentic AI in IDEs
if [[ "$TERM_PROGRAM" == "vscode" || "$TERMINAL_EMULATOR" == "JetBrains-JediTerm" ]]; then
  echo "IDE agentic environment detected, not loading full shell integrations"

  # Keep only essential settings for agents
  export PS1='\$ '  # Minimal prompt

else
  # Load full Bash environment

  # Custom prompt (e.g., Starship, custom PS1)
  if command -v starship &> /dev/null; then
    eval "$(starship init bash)"
  else
    # ... Add your own PS1 variable
  fi

  # Load additional integrations
fi

# Always load essential environment variables and aliases

Still having issues?

Contact your GitLab administrator for assistance.