7. Troubleshooting

Common integration failures and fixes for the Ledger Multisig API tutorials.

TypeError: SafeApiKit is not a constructor

Cause

ESM/CJS interop differences in @safe-global/api-kit and @safe-global/protocol-kit.

Fix

Use interop-safe constructor resolution:

import SafeApiKitModule from "@safe-global/api-kit";

const SafeApiKit =
  typeof SafeApiKitModule === "function"
    ? SafeApiKitModule
    : (SafeApiKitModule as unknown as { default: typeof SafeApiKitModule }).default;

Apply the same pattern for SafeModule from @safe-global/protocol-kit.

isExecuted is false right after execution

Cause

Transaction Service indexing lag. Execution is on-chain, but API indexing is delayed.

Fix

• Wait 10-60 seconds, then query again.

• Verify by safeTxHash directly (getTransaction(safeTxHash)), not by "latest tx".

executeTransaction returns hash but tx failed

Cause

executeTransaction can return a submitted hash even when the EVM call reverts.

Fix

Always wait for receipt and check status:

const receipt = await publicClient.waitForTransactionReceipt({
  hash: executionResult.hash as `0x${string}`,
  timeout: 120_000,
});

if (receipt.status === "reverted") {
  throw new Error("Transaction reverted on-chain");
}

Wrong confirmationsRequired after threshold/owner change

Cause

Safe state changed on-chain, but Transaction Service still serves stale indexed state.

Fix

Poll getSafeInfo until threshold matches expected value before proposing the next tx in the flow.

getSafeBalances method missing

Cause

@safe-global/api-kit v2.5.7 does not wrap balances.

Fix

Use direct HTTP request:

GET /v2/safes/{address}/balances/

under the configured base URL:

https://app.multisig.ledger.com/api/safe-transaction-service/{chainId}

Private key formatting issues (0x0x...)

Cause

Mixing prefixed and non-prefixed private key formats.

Fix

Normalize once:

function normalizePrivateKey(key: string): `0x${string}` {
  return (key.startsWith("0x") ? key : `0x${key}`) as `0x${string}`;
}

RPC instability on Sepolia

Cause

Public Sepolia RPC endpoints can be slow or timeout.

Fix

• Retry with backoff.

• Use a dedicated provider (Alchemy/Infura/QuickNode) for stable integration tests.

URL confusion: public Safe service vs Ledger-hosted service

Cause

Using public Safe Transaction Service endpoints by mistake.

Fix

Use Ledger-hosted base URL:

https://app.multisig.ledger.com/api/safe-transaction-service/{chainId}

Transactions proposed through this backend appear in Ledger Multisig UI.

See also

• Tutorial index

• Transactions with Off-chain Signatures