Troubleshooting

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• package.json
• scripts/publish-check.sh
• src/lib/SuiModule/SuiModule.svelte
• src/lib/index.d.ts
• src/routes/+page.svelte
• tsconfig.json
• eslint.config.js
• src/app.html
• src/lib/SuiModule/index.d.ts
• src/lib/SuiModule/index.js

This document provides guidance for diagnosing and resolving common issues encountered while using the sui-svelte-wallet-kit. It covers problems related to wallet connection, zkLogin configuration, transaction signing, data fetching, and development environment setup.

Wallet Connection and Discovery

This section addresses issues with detecting and connecting to Sui wallets. The core logic for wallet discovery and connection management resides within the SuiModule component.

Sources: src/lib/SuiModule/SuiModule.svelte

Wallets Not Appearing in Modal

If a wallet you expect to see is not listed in the ConnectModal, it's likely an issue with the discovery process. The kit uses a multi-stage approach to find wallets.

The diagram below illustrates the wallet discovery and initialization flow.

Diagnostic Steps:

1. Check Discovery Logic: The initWalletDiscovery function is called on component mount. It runs refreshDiscoverySnapshot multiple times with increasing delays (0ms, 50ms, 200ms, 600ms, 1200ms) to detect wallets that initialize slowly.
   Sources: src/lib/SuiModule/SuiModule.svelte:1109-1116
2. Verify Wallet Installation: Ensure the wallet's browser extension is installed and enabled. The discovery process relies on @suiet/wallet-sdk's WalletRadar and the Wallet Standard's getWallets() function.
   Sources: src/lib/SuiModule/SuiModule.svelte:1020-1035, README.md:200-202
3. Check Console Logs: The module may log detected adapters and available wallets to the console. You can also manually check for detected wallets using the checkDetectedWallets function from the demo page, which reads the exported walletAdapters store.
   Sources: src/routes/+page.svelte:170-172, src/lib/SuiModule/SuiModule.svelte:1052-1075
4. Wallet Configuration: If you use walletConfig to customize ordering, ensure you are using the exact wallet name as detected by the browser. Wallets not in the ordering array are appended alphabetically.
   Sources: README.md:58-61, src/lib/SuiModule/SuiModule.svelte:979-1017

Auto-Connect Not Working

If the wallet does not automatically reconnect on page load, check the following:

1. autoConnect Prop: The SuiModule must be initialized with the autoConnect={true} prop.
   Sources: README.md:83, src/lib/SuiModule/SuiModule.svelte:1143-1145
2. localStorage: The auto-connect feature relies on a localStorage item with the key sui-module-connection. After a successful connection, this key stores the wallet name. The autoConnectWallet function reads this data to attempt reconnection. If localStorage is disabled or cleared, auto-connect will fail.
   Sources: src/lib/SuiModule/SuiModule.svelte:102-105, src/lib/SuiModule/SuiModule.svelte:348-361

Enoki zkLogin (Google Sign-In)

Troubleshooting for the Google zkLogin integration provided by Enoki.

"Sign in with Google" Option is Missing

This option only appears if the zkLoginGoogle prop is correctly configured and passes initial validation.

1. Configuration Prop: You must pass a valid zkLoginGoogle object to SuiModule. This object requires apiKey and googleClientId.
   Sources: README.md:144-150, src/lib/SuiModule/SuiModule.svelte:1169-1174
2. API Key Probe: The module performs a lightweight probe to https://api.enoki.mystenlabs.com/v1/app to validate the API key. If this probe fails with a 401 or 403 status, the _enokiKeyValid state is set to false, and the Google option is hidden. Check the browser's network tab and console for errors.
   Sources: src/lib/SuiModule/SuiModule.svelte:1058-1077

The following sequence diagram shows the API key validation process.

Invalid Configuration Errors

The module includes checks for common configuration mistakes and logs errors to the console.

Error Condition	Console Message Hint	Solution	Source
Missing apiKey or googleClientId	Enoki zkLogin is enabled but missing: ...	Provide the complete zkLoginGoogle object with both properties.	src/lib/SuiModule/SuiModule.svelte:177-185
API key seems too short	Enoki config looks unusual: apiKey too short	Verify you have copied the full API key from the Enoki Portal.	src/lib/SuiModule/SuiModule.svelte:188-198
Invalid Google Client ID format	googleClientId should typically end with .apps.googleusercontent.com	Ensure the Client ID is correct and ends with .apps.googleusercontent.com.	src/lib/SuiModule/SuiModule.svelte:188-198
Invalid API Key (server-side)	Enoki API key invalid or unauthorized	Generate a new API key from the Enoki Portal and update your configuration.	src/lib/SuiModule/SuiModule.svelte:1066-1068

Sources: src/lib/SuiModule/SuiModule.svelte:177-198, 1066-1068, README.md:133-135

Redirect URL Issues

OAuth flows require a redirect URL. The kit attempts to automatically determine a safe one, but explicit configuration is more reliable.

• The logic for selecting a URL is in getPreferredRedirectUrlForOAuth. It prioritizes redirectUrl, then redirectUrls, and finally falls back to the app's root path.
• If you experience redirect mismatches, explicitly set the redirectUrl property in your zkLoginGoogle configuration. This URL must be added to the "Authorized redirect URIs" in your Google Cloud Console for the corresponding OAuth 2.0 Client ID.

Sources: src/lib/SuiModule/SuiModule.svelte:141-149, src/lib/SuiModule/SuiModule.svelte:203-206

Transaction and Message Signing

Issues related to signing transactions or personal messages.

signAndExecuteTransaction Fails

If a transaction fails, the error is typically propagated from the wallet itself.

Diagnostic Steps:

1. Check Connection: Ensure useCurrentAccount() returns a valid account. The function will throw an error if no account is connected.
   Sources: src/lib/SuiModule/SuiModule.svelte:861-862
2. Examine Error Message: The catch block in your transaction logic will receive the error. The error.message often contains specific details from the wallet (e.g., "User rejected the transaction").
   Sources: src/routes/+page.svelte:101-103
3. Validate Transaction: Ensure the Transaction object is constructed correctly. The demo page provides a simple example of transferring 0 SUI to self.
   Sources: src/routes/+page.svelte:97-99

Message Signing Not Supported

Not all wallets support personal message signing.

• The canSignMessage() utility function checks if the connected wallet's adapter exposes the sui:signMessage or sui:signPersonalMessage feature.
• Your UI should use this function to conditionally show/disable the signing button.
• The demo page provides a list of wallets known to support this feature, such as Slush, Suiet, and OKX Wallet.

Sources: src/lib/SuiModule/SuiModule.svelte:929-944, src/routes/+page.svelte:502-514

Data Fetching Issues

Problems with fetching SUI balance or SuiNS names.

SUI Balance is Stale or Not Loading

1. Caching: The kit caches SUI balance to reduce network requests. The default Time-to-Live (TTL) is 2000ms. If the balance seems stale, this may be the reason.
   Sources: src/lib/SuiModule/SuiModule.svelte:400-402
2. Force Refresh: You can bypass the cache by calling refreshSuiBalance(address, { force: true }).
   Sources: README.md:297-299, src/routes/+page.svelte:420-424
3. Auto-Fetching: Ensure autoSuiBalance={true} is set on SuiModule for automatic balance updates on account or network changes.
   Sources: README.md:85, src/lib/SuiModule/SuiModule.svelte:1197-1204

SuiNS Names are Missing

1. Auto-Fetching: Ensure autoSuiNS={true} (the default) is set on SuiModule.
   Sources: README.md:84
2. Network: SuiNS names are network-specific. Ensure the connected wallet is on a network where the address has a registered name. The logic uses resolveAddressToSuiNSNames from @suiet/wallet-sdk.
   Sources: src/lib/SuiModule/SuiModule.svelte:365-392
3. No Name Registered: The address may simply not have a SuiNS name. The suiNames.value store will be an empty array.
   Sources: src/routes/+page.svelte:390-394

Build and Environment Setup

Problems related to your development environment, build process, or dependencies.

TypeScript Errors

If you encounter TypeScript errors, check your configuration.

• tsconfig.json: The README.md recommends specific compiler options for compatibility with Svelte 5 and modern tooling. Ensure your tsconfig.json is aligned.

  {
    "compilerOptions": {
      "moduleResolution": "bundler",
      "strict": true
    }
  }
  

  Sources: README.md:323-329, tsconfig.json
• Peer Dependencies: The kit requires svelte: ^5.0.0. Check your package.json to ensure the version is compatible.
  Sources: package.json:66-68

Package Integrity Issues

If you are forking or contributing to the library, you might face issues with the package build.

• Build Script: The primary build command is pnpm run prepack, which executes svelte-package. This generates the dist directory.
  Sources: package.json:25-26
• Validation Script: The repository includes a publish-check.sh script. This script verifies that all required files (package.json, README.md, etc.) are present and that the dist directory and its main entry points (index.js, index.d.ts) exist after a build. Running this script can help diagnose packaging problems.
  Sources: scripts/publish-check.sh