FuelLabs/fuels-ts · error · FuelError

DECODE_ERROR

DECODE_ERROR

Error message

Invalid TxPointer scalar string length ${value.length}. It must have length 12.

What it means

Thrown by TxPointerCoder.decodeFromGqlScalar when the GraphQL scalar string representing a transaction pointer is not exactly 12 characters long. The decoder expects an 8-char hex blockHeight segment followed by a 4-char hex txIndex segment (matching fuel-vm's TxPointer parsing). Any other length is treated as malformed input and rejected before parsing begins.

Source

Thrown at packages/transactions/src/coders/tx-pointer.ts:26

  /** Transaction index (u16) */
  txIndex: number;
};

export class TxPointerCoder extends StructCoder<{
  blockHeight: NumberCoder;
  txIndex: NumberCoder;
}> {
  constructor() {
    super('TxPointer', {
      blockHeight: new NumberCoder('u32', { padToWordSize: true }),
      txIndex: new NumberCoder('u16', { padToWordSize: true }),
    });
  }

  public static decodeFromGqlScalar(value: string) {
    // taken from https://github.com/FuelLabs/fuel-vm/blob/7366db6955589cb3444c9b2bb46e45c8539f19f5/fuel-tx/src/tx_pointer.rs#L87
    if (value.length !== 12) {
      throw new FuelError(
        ErrorCode.DECODE_ERROR,
        `Invalid TxPointer scalar string length ${value.length}. It must have length 12.`
      );
    }
    const [blockHeight, txIndex] = [value.substring(0, 8), value.substring(8)];
    return {
      blockHeight: parseInt(blockHeight, 16),
      txIndex: parseInt(txIndex, 16),
    };
  }
}

View on GitHub (pinned to b3f37c91ac)

Solutions

1. Inspect the exact value passed to decodeFromGqlScalar; strip any '0x' prefix before calling it.
2. Verify the fuel-core node version matches the SDK's expected TxPointer format (8 hex chars blockHeight + 4 hex chars txIndex).
3. If consuming GraphQL data, check the schema/response for the txPointer field and confirm it is a 12-char hex string.
4. Add a length/format precondition in your own code: if (typeof v === 'string' && /^[0-9a-f]{12}$/i.test(v)) before decoding.

Example fix

// before
TxPointerCoder.decodeFromGqlScalar(rawTxPointer); // rawTxPointer = '0x000000010002'

// after
const clean = rawTxPointer.startsWith('0x') ? rawTxPointer.slice(2) : rawTxPointer;
TxPointerCoder.decodeFromGqlScalar(clean);

function isTxPointerScalar(v: unknown): v is string {
  return typeof v === 'string' && /^[0-9a-fA-F]{12}$/.test(v);
}
// before decoding:
if (!isTxPointerScalar(raw)) throw new Error(`bad txPointer scalar: ${String(raw)}`);
TxPointerCoder.decodeFromGqlScalar(raw);

const isTxPointerScalar = (v: unknown): v is string =>
  typeof v === 'string' && v.length === 12 && /^[0-9a-fA-F]{12}$/.test(v);

try {
  const { blockHeight, txIndex } = TxPointerCoder.decodeFromGqlScalar(clean);
} catch (e) {
  if (e instanceof FuelError && e.code === ErrorCode.DECODE_ERROR) {
    // handle malformed scalar
  }
  throw e;
}

When it happens

Trigger: Calling TxPointerCoder.decodeFromGqlScalar(value) where value is a string of length != 12. This happens when the GraphQL response for a transaction's txPointer field is truncated, padded, prefixed with '0x', or null/empty. The check `value.length !== 12` runs before any substring parsing.

Common situations: A fuel-core node returns a txPointer scalar in an unexpected format (e.g. with '0x' prefix, or zero-padded to a different width). Upgrading fuel-core changes the scalar serialization. Mock/stub GraphQL responses in tests that hardcode a wrong-length txPointer string. Manually constructing a TxPointer from a hex string without stripping prefixes.

Related errors

• INVALID_INPUT_PARAMETERS
• INVALID_DATA
• LOG_TYPE_NOT_FOUND
• ENCODE_ERROR
• ENCODE_ERROR

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