FuelLabs/fuels-ts · error · FuelError

UNSUPPORTED_TRANSACTION_TYPE

UNSUPPORTED_TRANSACTION_TYPE

Error message

Unsupported transaction type: ${type}

What it means

Thrown by UpgradePurposeCoder.encode when the upgradePurposeType.type is neither UpgradePurposeTypeEnum.ConsensusParameters (0) nor UpgradePurposeTypeEnum.StateTransition (1). The switch only handles those two enum members; any other numeric value falls into the default branch. The error reports the unsupported type discriminator that was passed in.

Source

Thrown at packages/transactions/src/coders/upgrade-purpose.ts:61

    switch (type) {
      case UpgradePurposeTypeEnum.ConsensusParameters: {
        const data = upgradePurposeType.data as ConsensusParameters;

        parts.push(new NumberCoder('u16', { padToWordSize: true }).encode(data.witnessIndex));
        parts.push(new B256Coder().encode(data.checksum));
        break;
      }

      case UpgradePurposeTypeEnum.StateTransition: {
        const data = upgradePurposeType.data as StateTransition;

        parts.push(new B256Coder().encode(data.bytecodeRoot));
        break;
      }

      default: {
        throw new FuelError(
          ErrorCode.UNSUPPORTED_TRANSACTION_TYPE,
          `Unsupported transaction type: ${type}`
        );
      }
    }

    return concat(parts);
  }

  decode(data: Uint8Array, offset: number): [UpgradePurpose, number] {
    let o = offset;
    let decoded;

    [decoded, o] = new NumberCoder('u8', { padToWordSize: true }).decode(data, o);
    const type = decoded as UpgradePurposeTypeEnum;

    switch (type) {
      case UpgradePurposeTypeEnum.ConsensusParameters: {

View on GitHub (pinned to b3f37c91ac)

Solutions

1. Ensure upgradePurposeType.type is exactly UpgradePurposeTypeEnum.ConsensusParameters or UpgradePurposeTypeEnum.StateTransition (import the enum, do not hardcode numbers).
2. If a new upgrade purpose type was added upstream, upgrade fuels to a version whose UpgradePurposeTypeEnum includes it.
3. Add a type guard that narrows UpgradePurpose before calling encode.
4. Avoid 'as any' / 'as UpgradePurpose' casts on objects built from untrusted sources.

Example fix

// before
const purpose = { type: 2, data: { bytecodeRoot: '0x...' } } as UpgradePurpose;
coder.encode(purpose);

// after
import { UpgradePurposeTypeEnum } from '@fuels/transactions';
const purpose = {
  type: UpgradePurposeTypeEnum.StateTransition,
  data: { bytecodeRoot: '0x...' }
};
coder.encode(purpose);

import { UpgradePurposeTypeEnum } from '@fuels/transactions';
function isValidPurposeType(t: unknown): boolean {
  return t === UpgradePurposeTypeEnum.ConsensusParameters ||
         t === UpgradePurposeTypeEnum.StateTransition;
}
if (!isValidPurposeType(purpose.type)) throw new Error('bad upgrade purpose type');
coder.encode(purpose);

const isUpgradePurpose = (p: unknown): p is UpgradePurpose =>
  typeof p === 'object' && p !== null && 'type' in p && 'data' in p &&
  (((p as any).type === UpgradePurposeTypeEnum.ConsensusParameters) ||
   ((p as any).type === UpgradePurposeTypeEnum.StateTransition));

try {
  const bytes = coder.encode(purpose);
} catch (e) {
  if (e instanceof FuelError && e.code === ErrorCode.UNSUPPORTED_TRANSACTION_TYPE) {
    // reject unsupported upgrade purpose
  }
  throw e;
}

When it happens

Trigger: Calling encode({ type: <number>, data: ... }) on an UpgradePurpose where type is not 0 or 1 — e.g. type: 2, type: -1, type: undefined, or type: 'StateTransition' (string instead of enum value). Reaches the default branch of the switch in encode().

Common situations: Hand-constructing an UpgradePurpose object with a wrong/typo'd type value. Using a stale enum constant after a SDK upgrade that renumbered the enum. Passing a plain object literal where TypeScript narrowing was bypassed (any cast). Decoded data fed back into encode from an incompatible fuel-core version that introduced a new purpose type.

Related errors

• INVALID_DECODE_VALUE
• DECODE_ERROR
• INVALID_TRANSACTION_INPUT
• INVALID_TRANSACTION_OUTPUT
• INVALID_POLICY_TYPE

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