Skip to content

Troubleshooting Guide

This troubleshooting guide covers common issues faced by developers when integrating Web3 apps with the Arcana Auth SDK for user onboarding and signing blockchain transactions.

Configuration Issues

Cannot turn off UI for wallet mode.

Arcana Auth SDK allows developers to manage the dApp user experience for signing blockchain transactions with the Arcana wallet. After installing the Auth SDK, during integration with the app, create a new AuthProvider instance and specify appropriate wallet visibility mode through the alwaysVisible parameter. See the Arcana wallet configuration guide for details.

Registered app does not show up in the 'Manage Apps' screen on the Developer Dashboard.

After logging into the Arcana Developer Dashboard, you should see any registered apps in previous sessions in the 'Manage Apps' dashboard screens. There is one card per registered application.

If you do not see your registered application card, check if you used a different social provider or email ID to log into the dashboard. Arcana supports aggregate login feature whereby if a developer uses different social providers to log into the dashboard in subsequent logins, both logins will be recognized as a single developer. This feature works if the same email ID is used by the developer across social providers.

Note: If you are migrating to the latest Arcana Auth SDK release from versions older than v1.0.0, you will not see your pre-registered apps in the dashboard due to some breaking changes. You need to re-register your apps again.

Aggregate login does not work when GitHub is one of the providers used to login into the Arcana Developer Dashboard.

Issue Details

A developer logs into the Arcana Dashboard for the very first time, using social authentication provider, say P1. The dashboard shows the 'Manage Apps' screen with the 'create new dApp' wizard and zero registered app configuration profile cards. The developer can register a new application and obtain a unique Client ID say Addr1. This will create a new app configuration profile card on the 'Manage Apps' screen for the newly registered app. Now if the developer logs out and logs back in using a different social authentication provider, say P2, Arcana Network can recognize that the login is by the same developer. This results in the dashboard displaying the 'Manage Apps' screen with the previously registered application configuration profile card. This behavior is supported only if the developer has the same email ID associated with both the social providers P1 and P2.

If the user has a different email ID associated with providers P1 and P2 then during the second login with a different provider, the same developer cannot be recognized and associated with the apps registered earlier using the different social provider. The dashboard considers login with a new provider (different email ID) as a new identity and assumes this is a fresh login by a new developer. It brings up the 'Manage Apps' screen where the same user will not be able to see the application configuration card that was present earlier while logging in with a different social provider.

If one of the providers is GitHub, then even if the same email ID is associated with all providers, Arcana Network may fail to associate the GitHub identity of the same developer with other providers.

Is there a way to get this working?


The aggregate login feature of Arcana Network allows an application developer to login into the dashboard using any supported social authentication mechanism and register and configure their application.

With GitHub, the behavior is different, only if the GitHub user settings are not in place. To ensure the same behavior as other social authentication providers, in the case of GitHub, make sure that you specify the following details in GitHub Settings:

1. In your GitHub profile setting, allow your email to be visible
2. In the GitHub Email Settings preferences, make sure you do not select the checkbox which says 'Keep my email address private'.

Refer to the figure below for details:

GitHub Profile email visible GitHub Email Settings not private

Auth Issues

Configured social providers do not show up in the wallet UI with v1.0.0.

If you are using an older version of the Arcana Auth SDK before v1.0.0, simply upgrading the package to v1.0.0 or beyond is not sufficient. Your older app configuration settings will no longer work. If you allow users to log in, their auth plug-and-play pop-up UI will not show any of the configured social providers.

Please follow the instructions in the Migration to v1.0.0 Guide before integrating with v1.0.0 Auth SDK. We highly recommend that you use the latest Auth SDK.

If your app users continue to see the same issue of social providers not showing after migrating properly, please double-check the Client ID that is specified at the time of instantiating the AuthProvider. If you are using v1.0.0, and do not explicitly specify any network value while instantiating the AuthProvider, then by default 'Mainnet' is selected. In this case, make sure you provide the Client ID assigned to your app's 'Mainnet' configuration profile. If you specify the wrong Client ID then you will not see the social providers when the wallet UI comes up after login.

If you choose to specify the network parameter as the 'testnet', then make sure you specify the Client ID corresponding to the 'Testnet' configuration profile of your app from the dashboard.

Error: Wallet is not initialized.


Wallet Not Initialized Error


This error is caused due to incorrect integration of the Auth SDK. While integrating with the Auth SDK, you need to perform the following key steps in the suggested order:

  1. First, install the Auth SDK.

  2. Next, create an AuthProvider instance.

  3. Lastly, initialize the AuthProvider by calling init() function. This is important as it initializes the embedded Arcana wallet. Only after a successful login, the wallet is visible in the context of an application.

See integration code sample for more details.

User could log in to the Web3 app but subsequent login fails after a developer enables the 'global keys' feature in the app.

By default, Arcana Auth is configured to allow app-specific keys for the Web3 apps that integrate with the SDK. Developers can begin deploying their apps on the Arcana Testnet and then deploy them on the Arcana Mainnet. To use the global keys feature in their apps, the developers are required to fill up an online form, submit it and wait for approval from the Arcana team before global keys are enabled for an app. The status of the feature request is displayed in the Arcana Developer Dashboard. While the feature is in 'review' status, the app can be deployed on the Arcana Testnet and users are allowed to log in and use the app.

While an app is switching over from the default 'app-specific' keys configuration to the 'global keys' configuration, the developer may choose to allow app users to log in before the global features option is approved. Users that log in before the global keys are approved will be assigned 'app-specific' keys. There is some part of key metadata that is stored locally in the authenticated user's device. In this case, once the feature gets approved, the user keys are re-assigned. The keys change from 'app-specific' to 'global keys' and this results in new key metadata. There is a mismatch between the keys or wallet addresses already in use by the users and the new global keys that are now reconfigured for the app users. As a result, users will not be able to log in to the app anymore.

To fix this issue, the user needs to clear the local storage used by the Arcana wallet on their device by clearing the browser cache and then attempting another login from a fresh browser window.

Last update: March 7, 2023 by shaloo, shalz