Troubleshooting

The android library uses callbacks to return the results of web requests to your application. If something goes wrong and you are having trouble with the android library, there are some steps you can take to figure out what the issue might be.

HTTP Debug Logging

Walking through stacktraces isn't always the best way to find a solution, so if you need more information about a request you can enable HTTP debug logging. You must first enable it on your instance of the client within your application, and then execute an adb command to send the output to logcat.

Add the following lines to programmatically configure the client for debug logging.

Client myClient = new Client.Builder(
        your_app_key,
        your_app_secret,
        this.getApplicationContext()).build();
myClient.enableDebugLogging();

Then, when your device is online and connected (execute adb devices to ensure you see it), you can run the following command to print out useful request/response information from the network layer of the library.

adb shell setprop log.tag.HttpTransport DEBUG

You will see detailed information in Logcat including HTTP headers and request bodies.

03-06 15:18:28.815: DEBUG/HttpTransport(31161): -------------- REQUEST  --------------
        GET https://baas.kinvey.com/appdata/kid_TPXLFgllAM/Updates/?limit=10&query=%7B%7D&sort=%7B%22_kmd.lmt%22%20:%20-1%7D
        Accept-Encoding: gzip
        Authorization: <Not Logged>
        User-Agent: android-kinvey-http/3.0.0
        x-kinvey-device-information: Samsung/Galaxy_Nexus Android 4.2.2 a3206c98-6591-36c7-b67a-396f7155a857
03-06 15:18:28.815: DEBUG/HttpTransport(31161): curl -v --compressed -H 'Accept-Encoding: gzip' -H 'Authorization: <Not Logged>' -H 'User-Agent: android-kinvey-http/2.0.4' -H 'x-kinvey-device-information: Samsung/Galaxy_Nexus Android 4.2.2 a3206c98-6591-36c7-b67a-396f7155a857' -- https://baas.kinvey.com/appdata/kid_TPXLFgllAM/Updates/?limit=10&query=%7B%7D&sort=%7B%22_kmd.lmt%22%20:%20-1%7D
03-06 15:18:29.065: DEBUG/HttpTransport(31161): -------------- RESPONSE --------------
        200 OK
        Connection: keep-alive
        Content-Length: 160
        Content-Type: application/json; charset=utf-8
        Date: Wed, 06 Mar 2013 20:18:30 GMT
        Server: nginx
        X-Android-Received-Millis: 1362601109057
        X-Android-Sent-Millis: 1362601108827
        X-Kinvey-API-Version: 4
        X-Kinvey-Request-Id: f4691d77975b4cce888f478a2f1adb60
        X-Powered-By: Express
03-06 15:18:29.065: DEBUG/HttpTransport(31161): Total: 160 bytes
03-06 15:18:29.065: DEBUG/HttpTransport(31161): [{"_acl":{"gr":true,"gw":false,"creator":"513652b3d04b27a33c00085a"},"_kmd":{"lmt":"2013-03-06T16:27:51.281Z"},"text":"Hello","_id":"51376e8748722432050001ff"}

The first line under -------------- REQUEST -------------- reveals the HTTP verb and url used for this specific request. Below that is the headers, and below those are the JSON payload (if any, note the above request is a GET and does not send JSON).

Similarly, the first line under -------------- RESPONSE -------------- will show the response code, followed by the headers, and ended with the JSON response data. Note the above request returns an entity with a "text" value of "Hello". If an error has occurred with a request, the status code will not be 200, and the JSON response will contain details about the issue.

Error Reporting

All Kinvey REST APIs return error responses using standard HTTP error codes. The error reporting is designed to make the APIs more usable—easy to implement and debug. Starting with API version 1, error responses are consistent across all REST API endpoints and use a structured format.

Every error response uses a universal dictionary to describe the error. The dictionary may see some updates from time to time but any updates are only expected to add new types of errors. Individual REST API methods will describe any behavior that diverges from the dictionary.

The body of the response contains information on the error. The body is JSON formatted like regular responses. Errors are guaranteed to remain unchanged when using a specific API version. Each error response body contains an HTTP response Status Code and up to three attributes: two mandatory and one optional, as described below.

• The error attribute is always present. It contains a String value representing the error type.
• The StatusCode is the HTTP response code associated with the error.
• The description attribute is always present. It contains a short user-friendly description of the error. You can pass the description up to the application user if you desire. Kinvey deserves the right to change the exact text of a description depending on developer feedback.
• The debug attribute is optional and exists solely to help debug the error. An app may choose to log this debug message if the application is running in debug mode. The Kinvey backend may or may not populate this attribute depending on the exact scenario encountered. The goal with this attribute is to provide useful information that will make it very easy to isolate the root cause and implement a fix.

Handling Errors

If an error occurs while the library is executing a request, details of the exception will be returned to your application via the onError(Throwable error) method of the callback. This handles both errors that occur on the client as well as errors that are returned from the service.

If the error comes from Kinvey, it will be of the type KinveyJsonResponseException. Within your onError method, you can perform an instanceof check and then cast appropriately. If the exception has occured on the client, either before executing the request or after it has returned, it will fail this instanceof and can be handled as any other android exception would be.

Client-Side errors

When an error is passed to the onError method, you can call error.printStackTrace() to get the full stack trace printed to the logs, or error.getMessage() to get an idea of the root cause. Two of the most common client-side issues are:

• Host Not Found Exception - If you see this, ensure your device has an active internet connection. This can be tested by opening up the browser on the device, and attempting to visit any website. If you want your app to be responsive even when there is not an active internet connection, take a look at our DataStore guide

• Unable to Parse Response - This issue occurs because the JSON response from Kinvey cannot be parsed into the defined GenericJson class. If there have been any changes in the types of fields within your model, double check that they are consistent with what's in the backend. For example, if an "age" field is changed from an int to a String, whenever an entity is retrieved from your backend where this value is a number will fail with this error message.

Post on our support forums if you have trouble figuring out the cause or solution to an issue, and we can point you in the right direction.

Server-returned errors

When an error is returned from Kinvey, it will be of the type KinveyJsonResponseException. After performing an instanceof check, you can cast the error and then access more explicit information.

a KinveyJsonResponseException contains debug information about the error, which can be accessed through the getDetails() method. The details contains an error message, a debug string, and a description.

In the table above, the values in the Error column can be accessed through the getDetails().getError() methods on an KinveyJsonResponseException

@Override
public void onFailure(Throwable error) {
  if (error instanceof KinveyJsonResponseException){
    KinveyJsonResponseException jsonError = ((KinveyJsonResponseException) error)
    Log.e(TAG, "description" + jsonError.getDetails().getDescription());
    Log.e(TAG, "debug" + jsonError.getDetails().getDebug());
    Log.e(TAG, "error" + jsonError.getDetails().getError());
  }
}