Troubleshooting

When errors/exceptions occur in the system, the API Microgateway throws error responses to the client by default. The following sections explain the different ways of troubleshooting common problems that might occur while you use the Microgateway.

Common exceptions and solutions

The table below shows the common exceptions that might occur when you are trying to use the API Microgateway, and how to fix them. These exceptions can happen due to misconfigurations.

Runtime errors

Error log Possible cause Resolution
micro-gw: Error occurred while trying to connect with server. Is the server running at https://localhost:9443?

The API Manager node (Publisher) is down when running the setup command in the Microgateway.

Verify the connectivity between the Microgateway and the API manager node.
Micro-gw: ERROR [src:0.0.0] - Error in client response : {message:"Connection refused: localhost/127.0.0.1:8080", cause:null} Connection to the backend is refused. Check the connection to the backend.
error [docker plugin]: Unable to build docker image: {"message":"invalid reference format: repository name must be lowercase"}

The name of the docker images should be in lower case.

When building the project with docker annotations, the docker image name is retrieved from the API name and version. If the API name contains a capital letter, then the docker image n ame would reflect that, resuling in this error.



When building the API microgateway project, provide a simple letter name for the docker image in the deployment.toml file as shown below.


[docker]
  [docker.dockerConfig]
    enable = true
    name = "hello_world"



ERROR [wso2/gateway:0.0.0] - Error occurred while reading the key validation response : {message:"Connection refused: localhost/127.0.0.1:9443", cause:null}
ERROR [wso2/gateway:0.0.0] - Error occurred while converting the authorized value from the key validation response to a
string value : {message:"'null' cannot be cast to 'string'", cause:null}

ERROR [wso2/gateway:0.0.0] - Error occurred while getting key validation information for the access token : {message:"call failed", cause:{message:"call failed", cause:{message:"'null' cannot be cast to 'string'", cause:null}, causes:[{message:"'null' cannot be cast to 'string'", cause:null}]}, causes:[{message:"call failed", cause:{message:"'null' cannot be cast to 'string'", cause:null}, causes:[{message:"'null' cannot be cast to 'string'", cause:null}]}]}

The Microgateway could not connect to the Key Manager for OAuth2 key validation. Check the connection between the Microgateway and the Key Manager.
ERROR [wso2/gateway:0.0.0] - Error occurred while reading the key validation response : {message:"General SSLEngine problem/192.168.8.101:9443", cause:null}
ERROR [wso2/gateway:0.0.0] - Error occurred while converting the authorized value from the key validation response to a
string value : {message:"'null' cannot be cast to 'string'", cause:null}
SSL hostname verification has failed in the key validation call.
The localhost hostname is supported by default.
You need to add the public certificate of the Key Manager to the Microgateway truststore. Also, make sure that you change the certificateAlias accordingly.
ERROR [ballerina/http] - Error while validating JWT token : {message:"Invalid signature", cause:null} JWT signature verification has failed.
Verify the following:
  • JWT signer’s public cert should be available in the Microgateway’s truststore.
  • The correct Certificate Alias should be given in the <MGW_HOME>/conf/micro-gw.conf file.

Toolkit errors

Error log Possible cause Possible reasons
micro-gw: Error in client response : {message:"Network is unreachable: www.mocky.io/54.194.152.6:80", cause:null}

A connection to the backend could not be established because the network is unavailable.

Verify the network stability.
ERROR {org.wso2.apimgt.gateway.cli.cmd.Main} - Internal error occurred while executing command.
com.github.jknack.handlebars.HandlebarsException: /home/kim/Downloads/wso2am-micro-gw-toolkit-x.x.x/resources/templates/service.mustache:36:87: java.lang.IllegalStateException: Can't resolve: 'doc'
This is due to an issue in the Service template.
  • Open the <MGW_HOME>/resources/templates file.
  • Remove the @swagger:ServiceInfo annotation-related configuration in the service.mustache template.
  • Re-run the setup command.

micro-gw: Project name `petstore` already exist.

You get this error when you re-run the micro-gw init <project-name> command while you already have a project with the same name (e.g., petstore ) in the current working directory.

Carry out one of the following actions to overcome this error.

  • Override the current project
    If you need to override the current Microgateway project, run the init command with the -f (--force) option. For example, use the following command if you are overriding the petstore project.

    micro-gw init <project-name> -f
  • Create a new project

    If you do not need to override the current Microgateway project, run the init command with another project name from another working directory.

    micro-gw init <project-name>

Runtime error responses

Error code Error response Possible reasons
101503 { "fault": { "code": "101503", "message": "Runtime Error", "description": "Error connecting to the back end" }
  • The network is not reachable by the backend.
  • The connection from the backend has been refused
  • 101504 { "fault": { "code": "101504", "message": "Runtime Error", "description": "Connection timed out" } }
  • The connection has timed out.
  • The connection has timed out from the Microgateway end.
  • Response is getting delayed and hence timeout occurs in the Microgateway side.
  • 900900 { "fault": { "code": 900900, "message": "Unclassified Authentication Failure", "description": "Unclassified Authentication Failure" } }
  • The Key Manager is down.
  • Runtime error codes

    Given below are some WSO2 API Microgateway specific error codes and their meanings.

    Error code Possible reason
    900901 The production/sandbox key offered by the requested endpoint is not specified.
    900900 API-M authentication related error.
    900901 Invalid access token.
    900902 Missing credentials.
    900903 Access token expired.
    900904 Access token inactive.
    900905 Incorrect access token type provided.
    900906 No matching resource found in the API for the given request.
    900907 The requested API is temporarily blocked.
    900908 Resource forbidden.
    900909 The subscription to the API is inactive.
    900910 The access token does not allow you to access the requested resource.
    900803 Application level throttled out.
    900804 Subscription level throttled out.
    900808 An internal error occurred in the Microgateway.
    900809 An internal error occurred in the Microgateway, since a subscription or application throttle policy is not deployed. This might be due to adding a throttle policy to API-M and not regenerating the Microgateway.

    Adding Debug Logs

    Micro gateway uses two types of logs to track realtime internal and external activities. Separate log files are created for each of those log types in the <MGW_RUNTIME_HOME> /repository/logs directory. The following illustrates the log types supported by the MGW and how those logs can be configured.

    How to enable debug log

    If we want to log any information that helps us identify what went wrong we can get information by enable DEBUG level. Ther are two ways to enable debug log.

    Method 1. We can set in the request command.

    sh gateway <path-to-MGW-executable-jar-file> --b7a.log.level=DEBUG

    Method 2. We can set in the micro-gw.conf file which is located in the <MGW-RUNTIME-HOME>/conf directory.

    [b7a.log]
      level = "DEBUG"
    How to enable HTTP trace log

    If we want to monitor the HTTP message flow through API Gateway and track the request headers, request payloads, response headers, response payloads etc of incoming and outgoing http traffic we can get information by enable HTTP trace log .

    Method 1. We can set in the request command.

    sh gateway <path-to-MGW-executable-jar-file> --b7a.http.tracelog.console=true

    Method 2. We can set in the micro-gw.conf file which is located in the <MGW-RUNTIME-HOME>/conf directory.

    [b7a.http]
    [b7a.http.tracelog]
    console = true
    Top