Error Handling

Common Errors

These are the errors you will most likely run into when building with Cascade.

RPC Connection Errors

If the Lumera RPC node is down or unreachable, client creation and blockchain transactions will fail:

try {
  const client = await createLumeraClient({ preset: "testnet", signer, address, gasPrice: "0.025ulume" });
} catch (err) {
  // "Failed to connect to RPC endpoint" or "ECONNREFUSED"
  console.error("Cannot reach RPC node. Check your network or try a different endpoint.");
}

Fix: Switch to a different RPC endpoint, or wait and retry. You can pass a custom endpoint instead of the preset:

const client = await createLumeraClient({
  chainId: "lumera-testnet-2",
  rpcUrl: "https://lumera-testnet-rpc.polkachu.com",
  lcdUrl: "https://lumera-testnet-api.polkachu.com",
  snapiUrl: "https://snapi.testnet.lumera.io",
  signer,
  address,
  gasPrice: "0.025ulume",
});

Insufficient Funds

Uploading requires LUME tokens to pay the action fee. If your wallet is empty:

"insufficient funds: 0ulume is smaller than 50000ulume"

Fix: Fund your wallet with testnet tokens from the Lumera faucet before uploading.

Keplr Extension Not Found

The user hasn't installed Keplr or the page loaded before the extension injected window.keplr.

Fix: Wait for the extension to load before accessing it:

async function waitForKeplr(timeout = 3000): Promise<boolean> {
  if (window.keplr) return true;
  return new Promise((resolve) => {
    const timer = setTimeout(() => resolve(false), timeout);
    window.addEventListener("keplr_keystorechange", () => {
      clearTimeout(timer);
      resolve(true);
    });
  });
}

Wallet Popup Rejected

When using Keplr or Leap, the user must approve signature requests. If they click "Reject":

try {
  await client.Cascade.uploader.uploadFile(file, params);
} catch (err) {
  if (err.message?.includes("Request rejected")) {
    console.error("Please approve the signature request to continue");
  }
}

Fix: Prompt the user to try again and approve the wallet popup. Cascade requires ADR-036 signatures for authentication, not transactions. Consider showing a pre-sign dialog explaining what is being signed. The user may see multiple popups during upload (layout, index, and auth).

Supernodes Unavailable

If no supernodes are online to handle your request:

"Task failed with status: sdk:supernodes_unavailable"

Fix: Wait a few minutes and retry. This usually means the testnet supernodes are temporarily down or overloaded.

Upload Timeout

Large files or slow networks can cause the task to exceed the default 5-minute timeout:

"Task timed out after 300000ms"

Fix: Increase the timeout in taskOptions:

const result = await client.Cascade.uploader.uploadFile(file, {
  fileName: "large-file.zip",
  isPublic: true,
  expirationTime: String(Math.floor(Date.now() / 1000) + 86400),
  taskOptions: {
    timeout: 600000, // 10 minutes
  },
});

Action Not Registered

The transaction went through but the SDK could not find the action_registered event in the response:

"action_registered event not found in transaction. Available events: coin_spent, coin_received, transfer, message, tx"

This usually means you are trying to upload too fast after creating the client, or the transaction failed silently on-chain.

Fix:

1. Add a short delay before uploading to let the chain finalize the transaction
2. Check that your transaction actually succeeded on the Explorer
3. Make sure you have enough funds to cover the action fee (the transaction may have failed due to insufficient gas)

Action Not Found (404 from SN-API)

The on-chain action was registered, but the Supernode hasn't indexed it yet, or the Action ID is invalid.

try {
  const stream = await client.Cascade.downloader.download("99999");
} catch (err) {
  // HttpError with statusCode 404
  console.error("Action not found. Check the Action ID.");
}

Fix: The SDK retries automatically (5 attempts, 3-second delays). If the issue persists:

1. Verify the action exists on-chain at https://portal.testnet.lumera.io
2. Increase the timeout in taskOptions
3. Try a different SN-API endpoint

Download Failed or Empty Stream

The Supernodes could not reconstruct the file. This can happen with very recent uploads (Supernodes are still processing) or if the action has expired.

Fix:

1. Wait a few minutes after upload before attempting download
2. Verify the action status: client.Blockchain.Action.getAction(actionId)
3. Check that state === "ACTION_STATE_DONE"

Private File Access Denied

Trying to download a private file from a wallet that did not upload it:

"failed to verify download signature"

Fix: Only the wallet that uploaded the file can download it when isPublic: false. Make sure you are connected with the correct wallet.

Built-in Retries

The SDK automatically retries failed HTTP requests with exponential backoff. The defaults are:

You can override these when creating the client:

const client = await createLumeraClient({
  preset: "testnet",
  signer,
  address,
  gasPrice: "0.025ulume",
  http: {
    timeout: 60000,
    retry: {
      maxAttempts: 5,
      initialDelay: 2000,
    },
  },
});

Task Options

Upload and download tasks are processed asynchronously by supernodes. The SDK polls for status until the task completes. You can tune this behavior:

taskOptions: {
  timeout: 300000,    // 5 min default, how long to wait before giving up
  pollInterval: 2000, // 2s default, how often to check task status
}

Getting Help

• Discord: discord.com/invite/qudewKS3kp
• GitHub Issues: LumeraProtocol/sdk-js/issues
• Explorer: portal.testnet.lumera.io

Next Steps