FuelLabs/fuels-ts · error · FuelError

CONTRACT_SIZE_EXCEEDS_LIMIT

CONTRACT_SIZE_EXCEEDS_LIMIT

Error message

Contract bytecode is too large. Please use `deployAsBlobTx` instead.

What it means

Thrown by ContractFactory.deployAsCreateTx() (packages/contract/src/contract-factory.ts:228) when this.bytecode.length exceeds consensusParameters.contractParameters.contractMaxSize. The Create transaction type has a hard ceiling on contract bytecode size enforced by chain consensus parameters; contracts that exceed it must be deployed as chunked blob transactions via deployAsBlobTx(). Note: the general deploy() method auto-routes to deployAsBlobTx() when bytecode exceeds the limit, so this error only fires when deployAsCreateTx() is called explicitly.

Source

Thrown at packages/contract/src/contract-factory.ts:228

      ? this.deployAsBlobTx(deployOptions)
      : this.deployAsCreateTx<T>(deployOptions);
  }

  /**
   * Deploy a contract with the specified options.
   *
   * @param deployOptions - Options for deploying the contract.
   * @returns A promise that resolves to the deployed contract instance.
   */
  async deployAsCreateTx<T extends Contract = TContract>(
    deployOptions: DeployContractOptions = {}
  ): Promise<DeployContractResult<T>> {
    const account = this.getAccount();
    const { consensusParameters } = await account.provider.getChain();
    const maxContractSize = consensusParameters.contractParameters.contractMaxSize.toNumber();

    if (this.bytecode.length > maxContractSize) {
      throw new FuelError(
        ErrorCode.CONTRACT_SIZE_EXCEEDS_LIMIT,
        'Contract bytecode is too large. Please use `deployAsBlobTx` instead.'
      );
    }

    const { contractId, transactionRequest } = await this.prepareDeploy(deployOptions);

    const transactionResponse = await account.sendTransaction(transactionRequest);

    const waitForResult = async () => {
      const transactionResult = await transactionResponse.waitForResult<TransactionType.Create>();
      const contract = new Contract(contractId, this.interface, account) as T;

      return { contract, transactionResult };
    };

    const waitForPreConfirmation = async () => {
      const transactionResult = await transactionResponse.waitForPreConfirmation();

View on GitHub (pinned to b3f37c91ac)

Solutions

1. Use factory.deploy() instead — it auto-selects deployAsBlobTx() when bytecode exceeds the limit.
2. Call factory.deployAsBlobTx() explicitly for large contracts.
3. If the create-tx path is required, reduce contract size (split into multiple contracts, optimize code, remove unused functions).

Example fix

// before
const result = await factory.deployAsCreateTx();

// after
const result = await factory.deploy();
// or explicitly:
// const result = await factory.deployAsBlobTx();

const { consensusParameters } = await account.provider.getChain();
const maxContractSize = consensusParameters.contractParameters.contractMaxSize.toNumber();

if (factory.bytecode.length > maxContractSize) {
  console.log(`Bytecode (${factory.bytecode.length}) exceeds max (${maxContractSize}); using blob tx`);
  await factory.deployAsBlobTx();
} else {
  await factory.deployAsCreateTx();
}

try {
  await factory.deployAsCreateTx();
} catch (e) {
  if (e instanceof FuelError && e.code === 'contract-size-exceeds-limit') {
    // Fall back to blob deployment
    await factory.deployAsBlobTx();
  } else {
    throw e;
  }
}

When it happens

Trigger: Calling factory.deployAsCreateTx() directly with bytecode larger than the chain's contractMaxSize consensus parameter (typically tens of KB). The limit is fetched from the provider's getChain() response.

Common situations: Large Sway contracts (complex logic, embedded data, many functions) that exceed the create-tx size ceiling; upgrading a contract that grew past the limit; explicitly choosing deployAsCreateTx for determinism but the contract is too large; chain parameter changes after a hard fork that lowered the max.

Related errors

• FUNDS_TOO_LOW
• TRANSACTION_FAILED
• INVALID_CHUNK_SIZE_MULTIPLIER
• MISSING_PROVIDER
• CONFIGURABLE_NOT_FOUND

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