unionlabs/union · error · Error

Invalid chain id

Error message

Invalid chain id

What it means

Thrown by createUnionClient, the single entry point of the Union TypeScript SDK. It routes the parameters to createEvmClient, createCosmosClient, or createAptosClient by checking membership of parameters.chainId in the evmChainId, cosmosChainId, and aptosChainId literal arrays; if no list contains the id, the chain is unsupported and client creation fails immediately.

Source

Thrown at typescript-sdk/src/mod.ts:183

 * Create Union Client for EVM, Cosmos, and Aptos
 */
export function createUnionClient(
  parameters: EvmClientParameters | CosmosClientParameters | AptosClientParameters,
):
  | ReturnType<typeof createEvmClient>
  | ReturnType<typeof createCosmosClient>
  | ReturnType<typeof createAptosClient>
{
  if (evmChainId.includes(parameters.chainId)) {
    return createEvmClient(parameters as EvmClientParameters)
  }
  if (cosmosChainId.includes(parameters.chainId)) {
    return createCosmosClient(parameters as CosmosClientParameters)
  }
  if (aptosChainId.includes(parameters.chainId)) {
    return createAptosClient(parameters as AptosClientParameters)
  }
  throw new Error("Invalid chain id")
}

/**
 * @example
 * ```ts
 * import { privateKeyToAccount } from "viem/accounts"
 * import { DirectSecp256k1Wallet } from "@cosmjs/proto-signing"
 * import { createUnionClient, hexToBytes } from "@union/client"
 *
 * const cosmosAccount = await DirectSecp256k1Wallet.fromKey(
 *   Uint8Array.from(hexToBytes(PRIVATE_KEY)),
 *   "stride"
 * )
 *
 * const clients = createMultiUnionClient([
 *   {
 *     chainId: "11155111",
 *     transport: http("https://rpc.sepolia.org"),

View on GitHub (pinned to 031785bb6d)

Solutions

1. Check the exported evmChainId, cosmosChainId, and aptosChainId unions from @union/client and use one of those literal values
2. Upgrade @union/client to the latest version, which usually adds newly supported chains
3. Verify formatting: EVM ids are decimal strings like "11155111", Cosmos ids like "stride-internal-1", Aptos ids per the SDK's list
4. If the chain is genuinely unsupported, request support or route through a supported chain's client

Example fix

// before
const client = createUnionClient({
  chainId: 11155111, // number, not in the string unions
  transport: http(rpc),
})

// after
const client = createUnionClient({
  chainId: "11155111", // literal from evmChainId
  transport: http(rpc),
})

import { cosmosChainId, evmChainId, aptosChainId } from "@union/client"

const isSupportedChainId = (id: string) =>
  evmChainId.includes(id as never) || cosmosChainId.includes(id as never) || aptosChainId.includes(id as never)

if (!isSupportedChainId(chainId)) {
  throw new Error(`Unsupported chainId ${chainId}; upgrade @union/client or use a listed id`)
}
const client = createUnionClient({ ...params, chainId })

import { evmChainId, cosmosChainId, aptosChainId } from "@union/client"

type SupportedChainId =
  | (typeof evmChainId)[number]
  | (typeof cosmosChainId)[number]
  | (typeof aptosChainId)[number]

const isSupportedChainId = (id: string): id is SupportedChainId =>
  (evmChainId as readonly string[]).includes(id) ||
  (cosmosChainId as readonly string[]).includes(id) ||
  (aptosChainId as readonly string[]).includes(id)

try {
  const client = createUnionClient(params)
} catch (error) {
  if (error instanceof Error && error.message === "Invalid chain id") {
    // show supported chains / offer chain selection UI
  }
  throw error
}

When it happens

Trigger: Calling createUnionClient with a chainId outside the SDK's supported sets: a testnet/deprecated id (e.g. an old rollup), a chain added in a newer SDK release than the one installed, a numeric string with wrong formatting ("0x1" vs "1"), or a typo like "strid-1".

Common situations: Upgrading a chain in your app before upgrading @union/client; using a freshly launched L2/L3 not yet in evmChainId; passing chain name instead of chain id; formatting mismatches between number and string chain ids.

Related errors

• No Aptos RPC URL found
• waiting for transaction failed
• simulation result not found
• Transaction failed: ${transaction?.vm_status} - ${JSON.strin
• hash not found

AI-assisted analysis of unionlabs/union@031785bb6d (2026-08-16). Data as JSON: /api/errors/0f2aada6af5d258b. Report an issue: GitHub.