Troubleshooting

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.ActiveUserErrorAn active user already exists.
Kinvey.APIVersionNotAvailableErrorThis API version is not available for your app. Please retry your request with a supported API version,
Kinvey.APIVersionNotImplementedErrorThis API version is not implemented. Please retry your request with a supported API version.
Kinvey.AppProblemErrorThere is a problem with this app backend that prevents execution of this operation. Please contact support@kinvey.com for assistance.
Kinvey.BadRequestErrorUnable to understand request.
Kinvey.BLErrorThe Business Logic script has an error. See debug message for details.
Kinvey.CORSDisabledErrorCross Origin Support is disabled for this application.
Kinvey.DuplicateEndUsersErrorMore than one user registered with this username for this application. Please contact support@kinvey.com for assistance.
Kinvey.FeatureUnavailableErrorRequested functionality is unavailable for the API version.
Kinvey.IncompleteRequestBodyErrorThe request body is either missing or incomplete.
Kinvey.IndirectCollectionAccessDisallowedErrorPlease use the appropriate API to access this collection for this app backend.
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.KinveyInternalErrorRetryThe Kinvey server encountered an unexpected error. Please retry your request.
Kinvey.KinveyInternalErrorStopThe Kinvey server encountered an unexpected error. Please contact support@kinvey.com for assistance.
Kinvey.KinveyErrorAn error has occurred. This is a general error.
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.PopupErrorAn error occurred with the popup.
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.
Kinvey.UserAlreadyExistsErrorThis username is already taken. Please retry your request with a different username.
Kinvey.WritesToCollectionDisallowedErrorThis collection is configured to disallow any modifications to an existing entity or creation of new entities.

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');
store.findById('entity-id')
  .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');
store.findById('entity-id')
  .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 open source and proprietary Java tools listed at Ask Ubuntu 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?