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. Follow configuring API Manager for more information |
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.
|
|
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:
|
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. |
|
|
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.
|
Runtime error responses¶
Error code | Error response | Possible reasons |
---|---|---|
101503 |
{
"fault": {
"code": "101503",
"message": "Runtime Error",
"description": "Error connecting to the back end"
}
|
|
101504 |
{
"fault": {
"code": "101504",
"message": "Runtime Error",
"description": "Connection timed out"
}
}
|
|
101505 |
{
"fault": {
"code": "101505",
"message": "Runtime Error",
"description": "Malformed URL"
}
}
|
|
900900 |
{
"fault": {
"code": 900900,
"message": "Unclassified Authentication Failure",
"description": "Unclassified Authentication Failure"
}
}
|
|
Runtime error codes¶
Given below are some WSO2 API Microgateway specific error codes and their meanings.
Error code | Error message | Description |
---|---|---|
900901 |
Sandbox key offered to the API with no sandbox endpoint | The production/sandbox key offered by the requested endpoint is not specified. |
900900 |
Unclassified authentication failure | An unspecified API-M authentication related error. |
900901 |
Invalid credentials | Invalid authentication information provided. |
900902 |
Missing credentials | No authentication information provided. |
900906 |
No matching resource found in the API for the given request | The requested path does not match any of the APIs. |
900907 |
The requested API is temporarily blocked | The lifecycle state of the API has changed to blocked state. |
900908 |
Resource forbidden | The application which is used to get the authentication token does not have a valid subscription to the API. |
900909 |
The subscription to the API is inactive | The status of the subscription has made inactive. |
900910 |
The access token does not allow you to access the requested resource | Cannot access the required resource with the provided access token. Check the valid resources that can be accessed with this token. Possibly token is missing the required scopes for the requested resource. |
900911 |
Invalid credentials | Invalid authentication information with Basic authentication. |
900912 |
Invalid format of the credentials | Basic authentication credentials are not in the correct format with <username>:<password> . |
900917 |
Invalid Authentication scheme | API cannot be accessed with the given authentication scheme. |
900800 |
Message throttled out | Message is throttled out because the API level limit is exceeded. |
900802 |
Message throttled out | Message is throttled out because the Resource level limit is exceeded. |
900803 |
Message throttled out | Message is throttled out because the Application level limit is exceeded. |
900804 |
Message throttled out | Message is throttled out because the Subscription level limit is exceeded. |
900805 |
Message blocked | Accessing an API which is blocked on user, IP, application, or API Context. |
900806 |
Message throttled out | Message is throttled out because the Custom policy level limit is exceeded. |
900808 |
Internal server error occured | An internal error occurred in the Microgateway. |
900809 |
Internal server error occured | This error is thrown when local throttling is used and either the application, API or subscription level policy is missing in the policies.yaml file. We need to prior define all the API, application and subscription level policies in polcies.yaml file. |