FuelLabs/fuels-ts · error · FuelError

TRANSACTION_NOT_FOUND

TRANSACTION_NOT_FOUND

Error message

Transaction not found for given id: ${id}.

What it means

Thrown by `getTransactionSummary()` when the provider's `getTransactionWithReceipts` GraphQL query returns a null transaction for the supplied id. The SDK treats a missing transaction as a hard error because it cannot decode receipts or build a summary without the on-chain record. This usually means the transaction was never included or has not yet been indexed.

Source

Thrown at packages/account/src/providers/transaction-summary/get-transaction-summary.ts:35

import type { AbiMap, GraphqlTransactionStatus, TransactionSummary } from './types';
/** @hidden */
export interface GetTransactionSummaryParams {
  id: string;
  provider: Provider;
  abiMap?: AbiMap;
}

export async function getTransactionSummary<TTransactionType = void>(
  params: GetTransactionSummaryParams
): Promise<TransactionResult> {
  const { id, provider, abiMap } = params;

  const { transaction: gqlTransaction } = await provider.operations.getTransactionWithReceipts({
    transactionId: id,
  });

  if (!gqlTransaction) {
    throw new FuelError(
      ErrorCode.TRANSACTION_NOT_FOUND,
      `Transaction not found for given id: ${id}.`
    );
  }

  const [decodedTransaction] = new TransactionCoder().decode(
    arrayify(gqlTransaction.rawPayload),
    0
  );

  let txReceipts: TransactionReceiptJson[] = [];

  if (gqlTransaction?.status && 'receipts' in gqlTransaction.status) {
    txReceipts = gqlTransaction.status.receipts;
  }

  const receipts = txReceipts.map(deserializeReceipt);

View on GitHub (pinned to b3f37c91ac)

Solutions

1. Confirm the transaction id is complete and correct (0x-prefixed 32-byte hash).
2. Verify the provider URL matches the network where the transaction was submitted.
3. Poll or wait for inclusion before calling getTransactionSummary (e.g. await `submitAndAwaitStatus` first).
4. If the tx was squeezed out, resubmit and use the new id.

Example fix

// before
const summary = await getTransactionSummary({ id: '0xabc...', provider }); // throws
// after
await txResponse.waitForPreConfirmation(); // ensure inclusion first
const summary = await getTransactionSummary({
  id: txResponse.id,
  provider,
});

const { transaction } = await provider.operations.getTransactionWithReceipts({ transactionId: id });
if (!transaction) throw new Error(`tx ${id} not found; verify network and inclusion`);

null

import { ErrorCode } from '@fuel-ts/errors';
try {
  return await getTransactionSummary({ id, provider });
} catch (e) {
  if (e.code === ErrorCode.TRANSACTION_NOT_FOUND) { /* wait for inclusion then retry */ }
  else throw e;
}

When it happens

Trigger: Calling `getTransactionSummary({ id, provider })` (directly or via `transactionResponse.getTransactionSummary()` / `assembleTransactionSummary`) with an id the node has no record of. The `gqlTransaction` object comes back falsy from the query.

Common situations: Querying a transaction id immediately after submission before it is indexed; typo or truncated transaction id; transaction was squeezed out and never landed; pointing the provider at a different node/network than the one that received the tx; querying testnet id against mainnet.

Related errors

• TRANSACTION_SQUEEZED_OUT
• TRANSACTION_FAILED
• GAS_LIMIT_TOO_LOW
• MAX_FEE_TOO_LOW
• MAX_INPUTS_EXCEEDED

AI-assisted analysis of FuelLabs/fuels-ts@b3f37c91ac (2026-08-12). Data as JSON: /api/errors/45a12f0e498e82bd. Report an issue: GitHub.