Troubleshooting

The content in this guide refers to the newly released version 3 of the library. You can still access the version 1.x guides here.

Version 1.x is now deprecated. We will continue to support 1.x through March 31, 2017 (End of Support - EOS). If you are currently using 1.x in your apps, you will need to upgrade your apps to 3.x before the EOS date. We have created a migration guide to help you.

This section will provide you with hints what to do if you’re having trouble with the library. If you cannot find an answer to your question, please contact us through the Kinvey Community Support forums.

Errors

On failure, all functions return an error object. This object holds the following properties:

  • name holds a generic error name. The name can be used to program against.
  • message contains a short, user-friendly, description of the error.
  • debug provides hints which might help you debug the error. This property is not always populated.
  • code set to the status code of a network response. Default value is -1.
  • kinveyRequestId set to the X-Kinvey-Request-Id header value for Kinvey API requests. Default value is undefined.

Not all errors thrown by the Kinvey API are represented in the list below. If an error is not supported it will be returned as an instance of Kinvey.KinveyError with the name property set to the name of the error and code set to the status code of the response returned from the Kinvey API. For a detailed list of possible errors returned by the backend please take a look at REST API Troubleshooting Guide.

The possible error types returned by the library is as follows:

ErrorDescription
Kinvey.KinveyErrorAn error has occurred. This is a general error.
Kinvey.ActiveUserErrorAn active user already exists.
Kinvey.FeatureUnavailableErrorRequested functionality is unavailable for the API version.
Kinvey.IncompleteRequestBodyErrorThe request body is either missing or incomplete.
Kinvey.InsufficientCredentialsErrorThe credentials used to authenticate the request are not authorized to run this operation. Please retry the request with appropriate credentials.
Kinvey.InvalidCredentialsErrorInvalid credentials. Please retry the request with correct credentials.
Kinvey.InvalidIdentifierErrorOne of more identifier names in the request has an invalid format.
Kinvey.InvalidQuerySyntaxErrorThe query string in the request has an invalid syntax.
Kinvey.JSONParseErrorUnable to parse the JSON in the request.
Kinvey.MissingQueryErrorThe request is missing a query string.
Kinvey.MissingRequestHeaderErrorThe request is missing a required header.
Kinvey.MissingRequestParameterErrorA required parameter is missing from the request.
Kinvey.MobileIdentityConnectErrorAn error has occurred with Mobile Identity Connect.
Kinvey.NoActiveUserErrorThere is not an active user.
Kinvey.NoNetworkConnectionErrorYou do not have a network connection.
Kinvey.NoResponseErrorNo response was provided for the request.
Kinvey.NotFoundErrorThe item was not found.
Kinvey.ParameterValueOutOfRangeErrorThe value specified for one of the request parameters is out of range.
Kinvey.QueryErrorAn error occurred with the query.
Kinvey.ServerErrorAn error occurred on the query.
Kinvey.SyncErrorAn error occurred during sync.
Kinvey.TimeoutErrorThe request timed out.

Error Handling

To check for certain errors, we recommend to check if the error is an instanceof of the error object listed in the Error Reporting section.

Example: Check if an error is an ActiveUserError

Kinvey.User.login('username', 'password');
  .catch(function(error) {
    if (error.name === 'ActiveUserError') {
      // ...
    }
  });

Example: Check if an error is a NotFoundError

var store = Kinvey.DataStore.collection('collection-name');
var stream = store.findById('entity-id');
stream.subscribe(null, function(error) {
  // A NotFoundError could have a different name depending on the response from
  // the Kinvey API. It is recommended to use instanceof instead.
  if (error.name === 'NotFoundError') {
    // ...
  }
});

You can also check if the error is of a certain type of error using the name property.

Example: Check if an error is an ActiveUserError using the name property

Kinvey.User.login('username', 'password');
  .catch(function(error) {
    if (error.name === 'ActiveUserError') {
      // ...
    }
  });

Example: Check if an error is a NotFoundError using the name property

var store = Kinvey.DataStore.collection('collection-name');
var stream = store.findById('entity-id');
stream.subscribe(null, function(error) {
  // A NotFoundError could have a different name depending on the response from
  // the Kinvey API. It is recommended to use instanceof instead.
  if (error.name === 'NotFoundError') {
    // ...
  }
});

Exceptions

If you are using promises, any exceptions thrown inside the then handlers will be caught by the promise. What this means is that the following:

promise
  .then(function() {
    throw new Error('I am just an error.');
  });

Will not cause the exception to be visible in the log panel of your browser or IDE. This can lead to confusion as it seems that everything went fine, while in reality, the exception is thrown but not reported. To correctly deal with exceptions in promises, consider the approach below.

promise
  .then(funtion() {
    throw new Error('I am just an error.');
  })
  .catch(function(error) {
    // Check whether the error is an exception.
    if (error instanceof Error) {
      // error holds the Error thrown in the then handler above.
      // error.message === 'I am just an error.';
    }
  });

The error.message and error.stack properties will provide insight in what went wrong, and where.

Debugging

The library uses loglevel to log information. The default log level is Kinvey.Log.levels.SILENT. You can change the log level as show below.

Kinvey.Log.setLevel(Kinvey.Log.levels.DEBUG);

From then on, the flow of every call you make will be printed out using loglevel. You might be able to identify the error by inspecting these messages. When contacting Kinvey, sending this log along will be of great help.

Tools

Mac users may wish to use WireShark or Charles.

Windows developers can use Fiddler which is the preferred tool at Kinvey.

There are a few free Java tools listed at StackOverflow and one can always use Firebug through Firefox, or the Developer Tools through Chrome.

SSL Load Error with CDN

With the release of iOS 9, Apple introduced "App Transport Security". For more information please refer to the What's New in iOS Guide.

In order to load the Kinvey PhoneGap SDK using the CDN, you will need to add the entry

<key>NSAppTransportSecurity</key>
<dict>
  <key>NSExceptionDomains</key>
  <dict>
    <key>cloudfront.net</key>
    <dict>
      <!--Include to allow subdomains-->
      <key>NSIncludesSubdomains</key>
      <true/>
      <!--Include to allow HTTP requests-->
      <key>NSTemporaryExceptionAllowsInsecureHTTPLoads</key>
      <true/>
      <!--Include to specify minimum TLS version-->
      <key>NSTemporaryExceptionMinimumTLSVersion</key>
      <string>TLSv1.1</string>
    </dict>
  </dict>
</dict>

to the info.plist file for the iOS application generated by the PhoneGap CLI. This will allow the library to be loaded using the CDN however we recommend that you do not disable App Transport Security. Instead, you should download the Kinvey PhoneGap SDK and save it to a file in your project. For more help please check out the PhoneGap Push Application.

Got a question?