Troubleshooting

You can resolve common issues with API Agent in Visual Studio Code, such as authentication errors or missing source IDs.

Unable to use API Agent

Symptoms: After you are redirected to Visual Studio Code, API Agent displays the following error message: Error unable to fetch user.

Causes: A problem with user authentication or API Agent configuration causes this issue.

Resolving the problem: Click the IBM API Agent menu and click New chat.

API Agent extension issues

Symptoms: API Agent extension window disappears

Resolving the problem

To activate the extension window, complete the following steps:

Enter CMD + SHIFT + P to open the Visual Studio Code command palette.
In the command palette, enter the following command:
```
View: Show IBM API Agent
```

API Agent reload and logout issues

Symptom

If you resume the chat after a period of inactivity, the system displays an error message Error: Unautho rized and automatically logs you out. You cannot continue the conversation without logging in again.

Cause

The IBM® API Connect token expires if the chat is not used for time. If you continue the conversation after the token expires, the system triggers an unauthorized error and forces logout.

Resolving the problem

Log in to the API Agent plug-in again to continue your work.
To properly clear resources, always use the logout option in the API Agent plug-in. Do not use the Visual Studio Code managed sign-out option.

Important: The API Agent plug-in is renamed from API Assistant. If you have the old version, delete it before you download the new one.

MCP server issue

Symptom

You cannot connect to the MCP server or do operations that require server communication. If you face any issues with the MCP server, ensure that the MCP server URL is correct and reachable and the bearer token is valid. API requests fail or display errors that are related to authentication or connectivity.

Cause

The following issues might be the cause of the problem:

The MCP server URL is incorrect or unreachable.
The bearer token that is used for authentication is invalid or expired.

Resolving the problem

To troubleshoot MCP server issues, complete the following checks:

Ensure that the MCP server URL you are using for the MCP server is correct and accessible.
Confirm that the MCP server is reachable from your network.
Make sure that the bearer token is valid and not expired. If necessary, generate a new token and update your configuration.

Missing or inaccessible tools

Symptom

Tools are missing or inaccessible in the MCP environment.
Commands or features that depend on these tools fail or display errors.

Cause

The following issues can lead to this issue:

The MCP server is not displaying its tools correctly.
Invalid or incomplete schemas are provided.
The MCP server is not running or is unreachable due to network or configuration issues.

Resolving the problem

To troubleshoot this issue, complete the following checks:

Verify that the MCP server is running and accessible.
Ensure that the server displays all required tools.
Check that valid schemas are provided for each tool.
Confirm network connectivity and correct configuration settings.

Execution failures

Symptom

Commands or tasks fail to run.
Errors occur during operation, often related to parameters or missing fields.

Cause

The following issues can lead to this issue:

Incorrect parameter formats.
Required fields are missing or improperly specified.
Underlying issues in the MCP server configuration or runtime.

Resolving the problem

To troubleshoot this issue, complete the following checks:

Double-check parameter formats and ensure that all required fields are provided.
Review the MCP server logs for detailed error messages.
Correct any configuration issues identified in the logs.

A parameter value includes another parameter name

Symptom

When you use slash commands, the system displays parsing errors.
Parameters are split incorrectly, causing unexpected behavior.
For example, if a parameter value contains another parameter name, the system misinterprets it as a new parameter:
```
title: param1 description: xyz
```

Cause

The following issues can lead to this issue:

Certain edge cases in slash command parsing occur when parameter values include text that resembles another parameter name.
The parser incorrectly identifies the embedded text as a separate parameter.

Resolving the problem

To troubleshoot this issue, complete the following checks:

Do not include parameter names inside the value of another parameter.
For example, avoid
```
title: param1 description: xyz
```
If a parameter value contains spaces or text that looks like another parameter name, enclose the value in quotations:
```
title: "param1 description: xyz"
```
Review your command for potential ambiguities and correct them before you run them.

Workspace changes are not updated automatically

Symptom

Workspace changes such as adding, deleting, or updating files are not reflected automatically in the Visual Studio Code plug-in view.

Cause

The plug-in does not track workspace changes in real time.

Resolving the problem

To troubleshoot this issue, complete the following steps

Manually refresh the Visual Studio Code plug-in view to display the most recent state.
Open the Visual Studio Code command palette and enter the following command:
```
API Agent: Refresh Webview
```
In Visual Studio Code, open Explorer, then return to the plug-in view.

Switching provider organizations or stacks

Symptom

When you log out of one stack or user and switch to another, the API Agent might use outdated session information. This issue can cause persistence problems in older versions.

Cause

The workspace state retains the previous session because the session was not cleared after logout. As a result, the API Agent continues to reference old credentials or stack details.

Solution

To resolve this problem, use one of the following methods:

From the Main menu , click New chat to stay in the same provider organization or click Switch organization to change the provider organization.
In the Command palette, run the following commands:
```
API Agent: Clear session from workspace state and reload
```
Note: This command clears the session and reloads the workspace.
Or
```
Developer > Reload window
```

Error when switching UI during an active chat

Symptom: When you start an API Agent chat session in API Manager and then switch to IBM API Studio (or vice versa) without closing the chat, you can see the following error when you try to run a prompt: Error: Error sending message.
Cause: The chat session stays linked to the area where it was started. Switching between API Manager and IBM API Studio without starting a new session can cause this error.

Solution

To avoid this issue, do the following actions:

Start a new chat session after switching between API Manager and IBM API Studio.
Complete your prompts before switching between API Manager and IBM API Studio.

Fixing incorrect tool or operation selection in a plan

Symptom: The API Agent creates a plan that uses an incorrect or undesired tool or tool operation.

Cause: The API Agent did not clearly understand from the prompt which tool or tool operation was best suited to perform the requested task.

Resolution

After the plan is displayed in your chat, you can instruct the API Agent to use a specific tool operation. For example, enter the following prompt:

Use the <name> tool instead