Basic Troubleshooting of WSO2 Applications with WSO2 MGW (Micro Gateway) Part-02

Basic Troubleshooting of WSO2 Applications with WSO2 MGW (Micro Gateway) Part-02

When a WSO2 application experiences issues, it is crucial to promptly identify and resolve these problems. This section covers the troubleshooting process specifically for the WSO2 Micro Gateway (MGW), which is a critical component in the handling of API traffic between clients and backend services.

Understanding Your Application Flow

Typical Application Flow:

IS (Identity Server) → MGW (Micro Gateway) → MI (Micro Integrator) → [Your backends (EX; database)]

Note: This flow serves as a generic example. Your specific application architecture may vary.

Troubleshooting the MGW (Micro Gateway)

The MGW primarily handles API traffic and can encounter specific issues that impact performance and availability. Below are common errors encountered in MGW logs and steps to resolve them:

1. Timeout Error


  • The gateway logs an idle timeout error before a response is initiated by the backend.

Example Command to Identify Errors:

cat microgateway.log | grep -i "Idle timeout triggered before initiating inbound response" | more

Example Output:

2024-04-20 08:06:54,351 ERROR [wso2/gateway/src/gateway/utils] - [Account-Details-API-1.0.0] [4fbdc7d8-994f-4816-94b0-4bda7d2480f3] Error in client response: error {ballerina/http}IdleTimeoutError message=Idle timeout triggered before initiating inbound response

Why Does This Issue Occur?

This error typically occurs under a few circumstances:

  • High Latency in Backend Services: If the backend service or the server that is supposed to handle the request takes too long to start sending the response, MGW might timeout waiting for it. This is common in scenarios where the backend is under heavy load or is slow.

  • Configuration Settings: WSO2 MGW, like many gateways, has configuration settings that define timeout durations for various stages of HTTP request handling. If the idleTimeout setting is too short for your backend's performance characteristics, it might prematurely close connections that are actually normal in terms of your backend's response times.

  • Network Issues: Occasionally, network latency or unreliability can delay the initiation of a response beyond the configured timeout period, especially in distributed environments or when interfacing with external services over the internet.

Resolving the Issue

To resolve or mitigate this issue, consider the following steps:

  1. Review and Adjust Timeout Settings:

    • Check the idleTimeout and other related timeout settings in your MGW configuration. Increase the timeout limit to accommodate the expected delay from your backend services.
  2. Optimize Backend Performance:

    • Look into optimizing the performance of the backend API. This might involve scaling up resources, optimizing database queries, or implementing more efficient code.
  3. Improve Network Stability:

    • Ensure that the network connections between MGW and the backend services are stable and fast. Consider using more reliable network infrastructure or closer geographical placement to reduce latency.
  4. Monitoring and Logs:

    • Implement comprehensive monitoring and logging to catch these errors and understand their patterns. This can help in proactive adjustment of configurations or in troubleshooting.
  5. Error Handling in Client Applications:

    • On the client side, implement robust error handling that can appropriately retry or handle failures due to such timeouts.

2. Connection Closure Error


  • The gateway logs an error indicating that the connection was closed by the remote client or host unexpectedly.

Example Command to Identify Errors:

cat microgateway.log | grep -i "Connection between remote client and host is closed" | more

Example Output:

2024-04-20 08:01:49,327 ERROR [wso2/gateway/src/gateway/utils] - [GePG-Payments-API-2.0.0] [3dd078f6-96b1-45e8-90d3-d6eff2914073] Error when sending response: error {ballerina/http}GenericListenerError message=Connection between remote client and host is closed

Potential Causes:

  • Client-Side Closure: The client (e.g., a user's browser or another service calling the API) might have closed the connection intentionally or due to a timeout or error on its end, which would stop the response from being fully transmitted.

  • Server-Side Issues: The server or the backend service might close the connection due to an internal error, a crash, or a misconfiguration that abruptly ends the session.

  • Network Interruptions: Disruptions in the network connecting the client and the server can prematurely end connections. This could be due to network hardware issues, misconfigured firewalls, or ISP problems.

  • Timeout Configurations: Unlike the "Idle Timeout" error which specifically relates to inactivity, this error could also be influenced by timeout settings that govern the maximum allowed connection duration, irrespective of activity.

Resolution Steps:

  1. Client and Server Logs:

    • Review logs on both the client and server sides to determine why the connection was closed. This might pinpoint whether the issue is on the initiating or receiving end.
  2. Check Timeout and Keep-Alive Settings:

    • Ensure that both client and server have appropriate timeout and keep-alive settings to prevent premature closure.
  3. Network Stability:

    • Examine the stability and configuration of the network infrastructure. Verify that firewalls and routers are properly configured to allow sustained connections.
  4. Error Handling and Retries:

    • Implement error handling that can detect closed connections and potentially retry sending the response, depending on the importance of the transaction.
  5. Monitoring and Alerts:

    • Use monitoring tools to watch the health of the network and services to get real-time alerts on these types of errors.

Differences Between These Errors

  • Timeout Error: Indicates a delay in response initiation, typically due to backend performance issues or network delays.

  • Connection Closure Error: Involves the termination of the connection by either party due to errors, misconfigurations, or network issues, often unexpectedly.

Error identify code (WSO2 MGW)

Error identify code (WSO2 MGW)Description
grep -i "Idle timeout triggered before initiating inbound response"The gateway logs an idle timeout error before a response is initiated by the backend.
grep -i "Connection between remote client and host is closed"The gateway logs an error indicating that the connection was closed by the remote client or host unexpectedly.


In conclusion, effectively troubleshooting WSO2 Micro Gateway (MGW) issues requires a thorough understanding of the application flow and the ability to identify common errors such as timeout and connection closure errors. By carefully reviewing and adjusting configuration settings, optimizing backend performance, ensuring network stability, and implementing robust monitoring and error handling mechanisms, you can significantly enhance the performance and reliability of your API traffic management. Staying proactive in identifying and resolving these issues will help maintain seamless communication between clients and backend services, ensuring a smooth and efficient operation of your WSO2 MGW setup.