FuelLabs/fuels-ts · error · FuelError

NOT_IMPLEMENTED

NOT_IMPLEMENTED

Error message

Invalid upgrade purpose

What it means

Thrown by `UpgradeTransactionRequest.toTransaction()` when `upgradePurpose.type` is neither `ConsensusParameters` nor `StateTransition`. The method assembles the on-chain `TransactionUpgrade` structure and reaches the else branch only for an unrecognized purpose discriminator. Coded as `NOT_IMPLEMENTED` because a new/unknown purpose type is not yet handled.

Source

Thrown at packages/account/src/providers/transaction-request/upgrade-transaction-request.ts:152

    let upgradePurpose: UpgradePurpose;

    if (this.upgradePurpose.type === UpgradePurposeTypeEnum.ConsensusParameters) {
      upgradePurpose = {
        type: UpgradePurposeTypeEnum.ConsensusParameters,
        data: {
          witnessIndex: this.bytecodeWitnessIndex,
          checksum: this.upgradePurpose.checksum,
        },
      };
    } else if (this.upgradePurpose.type === UpgradePurposeTypeEnum.StateTransition) {
      upgradePurpose = {
        type: UpgradePurposeTypeEnum.StateTransition,
        data: {
          bytecodeRoot: hexlify(this.upgradePurpose.data),
        },
      };
    } else {
      throw new FuelError(FuelError.CODES.NOT_IMPLEMENTED, 'Invalid upgrade purpose');
    }

    return {
      type: TransactionType.Upgrade,
      ...super.getBaseTransaction(),
      upgradePurpose,
    };
  }

  /**
   * Gets the Transaction ID by hashing the transaction
   *
   * @param chainId - The chain ID.
   *
   * @returns - A hash of the transaction, which is the transaction ID.
   */
  getTransactionId(chainId: number): string {
    return hashTransaction(this, chainId);

View on GitHub (pinned to b3f37c91ac)

Solutions

1. Set `upgradePurpose.type` to either `UpgradePurposeTypeEnum.ConsensusParameters` (with `checksum`) or `UpgradePurposeTypeEnum.StateTransition` (with `data` bytecodeRoot).
2. Use the `UpgradeTransactionRequest` constructor or factory helpers that accept a strongly-typed `UpgradePurposeLike`, not a plain untyped object.
3. Upgrade @fuel-ts packages together so the enum definition is consistent.

Example fix

// before
const req = new UpgradeTransactionRequest({ upgradePurpose: { checksum: '0x...' } });
// after
import { UpgradePurposeTypeEnum } from '@fuel-ts/transactions';
const req = new UpgradeTransactionRequest({
  upgradePurpose: {
    type: UpgradePurposeTypeEnum.ConsensusParameters,
    checksum: '0x...',
  },
});

import { UpgradePurposeTypeEnum } from '@fuel-ts/transactions';
function isValidUpgradePurpose(p: any): boolean {
  return p && (p.type === UpgradePurposeTypeEnum.ConsensusParameters || p.type === UpgradePurposeTypeEnum.StateTransition);
}
if (!isValidUpgradePurpose(config.upgradePurpose)) throw new Error('invalid upgrade purpose type');

function isUpgradePurpose(v: unknown): v is import('@fuel-ts/transactions').UpgradePurpose {
  const t = (v as any)?.type;
  return t === UpgradePurposeTypeEnum.ConsensusParameters || t === UpgradePurposeTypeEnum.StateTransition;
}

null

When it happens

Trigger: Constructing an `UpgradeTransactionRequest` with an `upgradePurpose` object whose `type` field is missing, undefined, or a value outside `UpgradePurposeTypeEnum`. Calling `.getTransactionId()` or sending the tx (which invokes `toTransaction()`).

Common situations: Building an upgrade transaction from a config object where `upgradePurpose` was not set; version mismatch where the enum gained a new purpose type not handled by your SDK build; serializing/deserializing an upgrade request that lost the type field.

Related errors

• INVALID_TRANSACTION_INPUT
• INVALID_TRANSACTION_INPUT
• Witness at index "${index}" was not found
• UNSUPPORTED_TRANSACTION_TYPE
• GAS_LIMIT_TOO_LOW

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