---
schema_version: "1"
id: 8b286ad32bf0b3b6542e163fd010dc8c45d28b6241cc54c7703752e6d22e7fb4
title: Troubleshoot Agent Networks
collection: mulesoft
version: current
locale: en-us
portal_url: https://docs.salesforce.com/mulesoft/current/en-us/agent-network/1.0/af-troubleshoot-agent-networks.md
canonical_url: https://docs.mulesoft.com/agent-network/1.0/af-troubleshoot-agent-networks
source_site: docs.mulesoft.com
content_type: documentation
content_hash: 92804d48a21a1216e14844f35dbd1c6ee827656a2750a4020282557702c5c005
description: MuleSoft Documentation Site
release: "1.0"
latest: false
---
---
product: Building Agent Networks
version: 1.0
---

# Troubleshoot Agent Networks

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Resolve common agent network errors and connectivity issues by enabling verbose logging, message
logging policies, and distributed tracing. Using logs and distributed traces, you can observe agents
and MCP servers and see how requests flow through brokers, which tools and policies apply, and where
failures or latency originate.

> [!NOTE] Use Agent Visualizer to
> [view metrics, logs, and traces](https://docs.mulesoft.com/agent-visualizer/troubleshoot-agent-network) for agents and
> MCP servers in your network.

## Enable Logging to Debug Agent Brokers

Enable logging and log levels from CloudHub 2.0 or Runtime Fabric:

1.  In Runtime Manager, navigate to the application for the agent broker.

2.  Choose one of these options to configure logging:

    - [CloudHub 2.0](https://docs.mulesoft.com/cloudhub-2/ch2-manage-app-logs#configure-log-levels-and-categories)

    - [Runtime Fabric](https://docs.mulesoft.com/runtime-fabric/latest/deploy-to-runtime-fabric#configure-logging-and-log-levels)

3.  Set the log level to Debug for these classes:

    - `com.mulesoft.modules.agent.broker` (For agent broker)

    - `INSECURE-LOGGING` (For content that can potentially contain sensitive information, such as
      LLM reasoning, and inputs and outputs from agents and assets defined in `tools` and `links`)

> [!IMPORTANT] `INSECURE-LOGGING` is very likely to contain sensitive information, such as
> personally identifiable information (PII). Make sure to disable it after troubleshooting is
> completed.

## Enable Message Logging Policy

Edit `agent-network.yaml` to set message logging for MCP servers and agents.

Message logging uses the
[Omni Gateway Message Logging policy](https://docs.mulesoft.com/gateway/latest/policies-included-message-logging). In
the `connection` section of the agent or MCP server instance you want to log, add the following
logging policy inside `policies`:

```yaml
policies: ## add the following inside the policy setting
  - ref:
      name: message-logging
      namespace: business_group_UUID
    configuration:
      loggingConfiguration:
        - itemName: "Payload"
          itemData:
            message: "#[payload]"
            firstSection: true
            secondSection: true
            level: "INFO"
        - itemName: "Headers"
          itemData:
            message: "#[attributes]"
            firstSection: true
            secondSection: true
            level: "INFO"
```

> [!NOTE] On non-US control planes, the value for the `namespace` parameter can change. In Exchange,
> check the business group in the API Gateway Message Logging Policy Template.

## Troubleshooting Common Issues and Errors

Use the steps in this section to diagnose and fix common problems in agent networks.

### Issue: Traces Not Shown

If Anypoint Monitoring isn’t showing traces for agents and MCP servers, check these settings:

- In API Manager, verify you’ve enabled the tracing policy for all brokers and agents.

- In the managed Omni Gateways, verify that you’ve enabled Distributed Tracing for ingress and
  egress.

### Issue: No Agent Network Commands in Anypoint Code Builder

If you installed Anypoint Code Builder successfully, but you don’t see agent network commands in the
interface, verify that you have the latest version of the Anypoint Extension Pack. Then, restart VS
Code.

### Issue: No Agent Network Deployment Targets

If you attempt to deploy an agent network, but you don’t see any deployment targets in Anypoint Code
Builder or Anypoint CLI, then you need to set up your target deployment space and set up gateways.
For instructions, see [Get Started with Agent Networks](https://docs.mulesoft.com/agent-network/1.0/af-get-started).

### Error: "Cannot complete task due to issue accessing reasoning engine"

This is a generic error that the broker issues when the LLM fails. To troubleshoot this error,
[enable the message logging policy](#enable-message-logging) on the LLM instance, and then review
the logs to determine the cause of the error.

### Error: "HTTP error 404: Agent card not found at /.well-known/agent-card.json"

You can encounter this error in two different scenarios:

1.  The agent card URL is incorrect. In this case:

    - Check that the URL you set on the connection ends with a `/`.

    - Use a browser or Postman to request the agent card URL by appending
      `.well-known/agent-card.json` to the connection URL, for example,
      `[https://ping-id-agent-url/pingid/.well-known/agent-card.json](https://ping-id-agent-url/pingid/.well-known/agent-card.json)`.

2.  The A2A agent is not configured to use A2A protocol version 0.3.0. In this case:

    - If you created the agent with MuleSoft, verify that you are using the latest version of the
      Anypoint Connector for A2A (A2A Connector).

    - If you are using an external agent, verify that it uses the A2A protocol version 0.3.0.

## See Also

- [Known Issues](https://help.salesforce.com/s/issues)