Skip to main content

Common Issues

All the common issues that may occur while developing.

When your app communicates with the master controller, there are chances that the communication gets interrupted or closed. So, you need to handle how to fix that issue. Here is the list of common issues that we faced and how we fix it. There are AST exceptions that your app can receive and you can check it only in the console as there is no proper error code is being received from MasterController SDK.


  1. Whenever there is a case where your app receives a Runtime error with AST Exception with some error code like 500-29. You can go to the SSMS portal of the server that you are using, you can find the portal URLs in the prerequisites and navigate to the Reporting section and check for the description. Please refer to the below screenshot for the navigation.

  2. Sometimes, while deleting a logged-in user, the master controller sends INVALID_USER_ID even though userId is correct. No proper use case is found for this.

  3. In case you are not receiving the transaction, you can try logout and login as it is possible that the current transaction is queued.

  4. UserId and tenantId make a login authentic(If we provide a userId that is already logged in with a different tenant Id, it will allow adding user).

    • UserId and TenantId both are independent to each other so same user may exist on multiple tenantId and if you provide same user with different tenantId then MC takes it as a new user.
  5. SM exception occurred: The state of the promise has already been set: Your app receives this error when the flow of events is disturbed. For example, we take the flow of activation.

    1. Your app send StartEventEx to the master controller and receive StartActivationUserIdAndCodeOnlyEvent
    2. Then you are supposed to send ProvideActivationCodeAndUserIdEvent, but suppose you send either ProvideActivationCodeAndUserIdForAddUserEvent or any other event
    3. Then, this exception occurs, you can have a look at the flow diagrams that we have mentioned in this document and avoid this error.
  6. Sometimes, the master controller stops responding: No use case or proper solution is found yet.

  7. Invalid State: This event is similar to the above point. When the above exception occurs, the master controller goes into an invalid state.

    1. For Android: You can use GetStateEvent to receive the last event that was triggered before an invalid state and continue the correct flow.
    2. For iOS:  In iOS, InvalidStateEvent is not received, a ticket is raised for this issue.
  8. Dynamic server changing does not work in iOS. If we change the server and trigger the start event, the master controller does not send a response, and the app gets stuck on the same screen. In Android, this case can be handled by triggering the restart event with the new SDK configurations. But, in iOS, there is no such restart event present in the master controller framework.

Add User

UserId and tenantId make a login authentic. If we provide a userId which is already logged in with different tenant Id, it will allow adding a user.

If we provide an incorrect tenant Id with the correct user Id, your app receives Invalid UserId status.

  • This is not an issue, UserIdentifier is a combination of userId & tenantId so if you provide wrong tenantId MC fetch the user from SSMS with given userId & tenantId and if user not found on that tenantId it return invalid userId.

AST Exception Cases:

  1. When we enter the wrong pin more than the specified retries allowed, then the application receives ErrorRuntimeEvent  ASTException 500-29 which indicates that the certificate of the device is locked. Then you need to go to the SSMS portal and unlock your device. Please follow the below steps to unlock your device

    1. Go to the Users section(which you can see in the above image) and search your user

    2. Then select the devices option(third icon from last in Actions column) and look for your device it will have the name of your device(refer to the device option in below image)

    3. select the checkbox for that row and unlock the device

    4. Now, you will be able to log in again.

  2. Digest app version: In this error, on the reporting section, it says "digest of the app version does not match to the one in database". This case occurs when a new version for the same app and user is created. In this case, you need to update the version of your app and re-register the app.

  3. User is not allowed to register the app: This error occurs when the user you are trying to use to register application is not the "app register user" for the application. This means that you have to activate the application with the user you have given, when you firstly added the version. If you have forgotten which is the "app register user" then you can go to the "Versions" tab of the SSMS portal and search for the respective application. The "app register user" for the application can be found in the "App-Register user" column of the entry of the app version. From there you can also change the "app register user" for the respective version of your application. See Register App Version in KOBIL Digitanium / KOBIL Digitanium+ for a description of how to register a new app version.

Integrity check failed

Possible causes:

  1. You modified already registered version. There can be a situation in which you have started to modify the already registered app version. Then you need to change the app version where the integrity check is disabled or disable the integrity check on the current version.                

  2. You have registered a version of a Debug build and are now trying to use a Release build or vice versa. Usually, you should register only release builds. Since they will go into production. But this can be an issue.

TLS connection errors

Typically, TLS communication happens when you send an event that triggers communication with a server, e.g. when you send a LoginEvent. If everything goes well, you will receive a corresponding ResultEvent with status OK, e.g. a LoginResultEvent. However, a lot of things that can go wrong during a TLS communication,starting with networking problems over server misconfigurations up to bad queries or server side errors that trigger error responses - everything is possible.

When something goes wrong, the first important step is to determine if you actually sent the request and if the answer has been received. If that is the case, you know that communication is at least basically working and that server or client are unhappy with the content of the communication, e.g. your authentication token might be expired. Otherwise, you might need to look at the network infrastructure (e.g. firewalls) or at server configurations (server logs might help to see if there are request from a client that the server refused to answer).

So, assuming you got a result event indicating an error, have a look at members error_code and error_description. This should already give you a good idea of what went wrong. A relatively common issue is that the certificate chain can not be verified, e.g. after the certificates on the server side expired or when the server certificate has been changed/updated and the trust store does not yet contain certificates matching the new certificates. In this case, you will typically see an error_description saying either "self signed certificate in certificate chain" indicating that the server provides a (new) certificate chain up to and including a self signed root certificate, however no certificate from that chain can be found in our trust store. Or you may see "unable to get local issuer certificate", meaning that the chain transmitted by the server ends at an intermediate CA which is neither in our trust store, nor is the issuer of this certificate to be found in our trust store. In this situation, it is easiest to analyze the list of certificates provided by the server and compare them against the list of certificates contained in the trust store and add a suitable certificate provided by the server (or the certificate of the issuer of the topmost certificate provided by the server) to the trust store. The certificates that the server provides can be seen either in a browser or by using a command such as openssl s_client -showcerts [host]:[port]. The trust store can be easily displayed by having all the certificates in a PEM file and running e.g. openssl storeutl -noout -text truststore.pem.

If you cannot figure out the issue based on the error_code and the error_connection the next step is to have a look at the logfile and see if that gives additional hints.