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 stop the Arcana wallet from being displayed in the app's context.

The Arcana Auth allows developers to manage the user experience for signing blockchain transactions. In effect, developers can integrate with the Arcana Auth SDK and control whether the Arcana wallet is always displayed once the user is authenticated in the app's context. Or they can choose to hide and show the wallet as per the app's business logic.

After installing the Arcana Auth SDK, during integration with the app, create a new AuthProvider instance and specify the wallet visibility mode as false. This ensures that the wallet does not display by default once the user is authenticated. With the alwaysVisible set to false, the developer can call theshowWallet() function to display the wallet when required. Irrespective of whether the wallet is visible or not, any blockchain transaction will result in a transaction notification. The user can view the notification in the app context and take appropriate action to dismiss the notification.

See the Arcana wallet configuration guide for details.

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

After logging into the Arcana Developer Dashboard, the developer can view all the apps that were registered earlier displayed as cards in the 'Manage Apps' screen. There is one card per registered application.

If you do not see your registered application card, check if you used a different social login provider or email ID to log into the Arcana Developer Dashboard. Arcana Auth supports aggregate login feature whereby if a developer uses different social login providers to log into the Arcana Developer 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 login 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 Arcana Developer 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 Developer Dashboard for the very first time, using social authentication provider, say P1. The Arcana Developer Dashboard displays the 'Manage Apps' screen with the 'Create New App' 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 Auth can recognize that the login is by the same developer. This results in the 'Manage Apps' screen displaying 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 login providers P1 and P2.

If the user has a different email ID associated 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 login provider. The Arcana Developer 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 login provider.

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

Is there a way to get this working?

Solution

The aggregate login feature of Arcana Auth allows an application developer to login into the Arcana Developer Dashboard using any supported authentication providers to register and configure the 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

Why do users experience a 'Redirect URI Mismatch' error during authentication?

This error shows up if the developer has not properly set up the social login provider during app registration and configuration using the Arcana Developer Dashboard.

Go to the Arcana Developer Dashboard and check the app settings in the Social Auth section. Note that the Redirect URI displayed for the app is exactly the same as the one you have specified in the social login provider OAuth settings. For example, in the case of social login provider 'Google', use Google Developer Console and check OAuth settings. Check the spelling of the Redirect URI specified against the entry for your app.
If you are deploying the app on the Mainnet, then make sure the Redirect URI displayed in the Mainnet configuration profile of the app in the Arcana Developer Dashboard is used in the social login provider settings.

Auth Issues

Configured social login providers do not show up in the Arcana 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 login providers.

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

If your app users continue to see the same issue of social login 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 a different Client ID during app integration with the SDK then you will only see the social login providers in the login UI that are associated with the specified Client ID.

If you choose to specify the optional network parameter as 'testnet' while instantiating the AuthProvider, then make sure you specify the Client ID corresponding to the 'Testnet' configuration profile of the app as displayed in the Arcana Developer Dashboard.

Error: Wallet is not initialized.

Issue

Wallet Not Initialized Error in a Web3 app. — Wallet Not Initialized

Solution

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

First, install the Arcana Auth SDK
Next, create an AuthProvider instance.
Lastly, initialize the AuthProvider by calling the init() function. This is important as it initializes the embedded Arcana wallet. Only after a successful login, the Arcana 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 SDK 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 Arcana 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.

Gasless Errors

Gasless transaction is failing with the generic error 'user0p execution failed'. What is the real cause of the error?

The Arcana Auth SDK leverages Biconomy Gasless SDK under the covers and is limited by the errors reported by the same. In case of generic errors such as 'user0p execution failed', or others that do not point to any actionable reason for failure, the app developers must use Tenderly to pin-point the exact cause of failure and then take corrective action. Learn more...

Cannot set up a gas tank for the chain my app supports?

Gas tanks are supported only for a selected bunch of chains. The Arcana SDKs are powered by Biconomy and limited to the networks supported by the same. See supported networks for details.

Gasless is enabled for the chain, transactions are successful but gas fees are charged, why is that?

There can be multiple reasons for the same:

Insufficient Gas: Gas tanks that are empty or do not have sufficient funds can cause this issue. In Layer 2 chains a minimum $1-2 and for Layer 1 chains, a minimum of $5-10 should be available in the gas tank for successful gasless transactions.
Wrong Network: Gasless works only for the blockchain network where gas tank is set up, not for other networks. If gas tank is set up for chain 1 and transactions are issued on chain 2 where no gas tank exists, the transaction will not be gasless.
Wrong Address: When gas tank is set up for a blocchain network, gasless user accounts for such networks are associated with two addresses, EoA and SCW. For other chains where no gas tank is set up, user accounts have only 1 traditional wallet address, the EoA address. If the transaction is issued using the EoA account, it will not be gasless even if there is a gas tank for the selected chain and there are funds in the tank. Only SCW addresses can be used for gasless transactions.
User Action Override: The developer may have set up the correct network and SCW address but the user may switch the wallet address from SCW to EoA using the wallet UI at runtime. In this case, the gas fees will be charged on EoA as the SCW address was not used to perform the transaction.
Other: There may be other reasons as well that can be due to the underlying gasless providers used by the Arcana Auth product. Learn more...

Gasless is enabled for the chain, gas tank has sufficient funds, user has funds in the wallet but the transaction, say sending 10 native tokens to another wallet, fails, why?

Check the wallet address that is being used to make this transaction of sending 10 native tokens. Gasless operations use SCW wallet address. If the user's EoA address has sufficient funds but the SCW wallet has zero or insufficient funds, less than 10 tokens, the transaction will fail. This is because for chains where gasless is enabled, SCW address is used to perform wallet operations and smart contract functions.

Last update: April 12, 2024 by shaloo, shaloo