What causes "A field for the case must be provided." in FuelLabs/fuels-ts?

Always set exactly one variant key on the enum value object.

FuelLabs/fuels-ts · error · FuelError

INVALID_DECODE_VALUE

INVALID_DECODE_VALUE

Error message

A field for the case must be provided.

What it means

Thrown by EnumCoder.encode when Object.keys(value) is empty — i.e. the enum value object has no variant field set. The message is the literal "A field for the case must be provided.". A Sway enum value must specify exactly one case, so an empty object {} is rejected. Note the code is INVALID_DECODE_VALUE even though it fires during encode (a known misnomer in the library).

Source

Thrown at packages/abi-coder/src/encoding/coders/EnumCoder.ts:65

  }

  #encodeNativeEnum(value: string): Uint8Array {
    const valueCoder = this.coders[value];
    const encodedValue = valueCoder.encode([]);
    const caseIndex = Object.keys(this.coders).indexOf(value);

    const padding = new Uint8Array(this.#encodedValueSize - valueCoder.encodedLength);
    return concat([this.#caseIndexCoder.encode(caseIndex), padding, encodedValue]);
  }

  encode(value: InputValueOf<TCoders>): Uint8Array {
    if (typeof value === 'string' && this.coders[value]) {
      return this.#encodeNativeEnum(value);
    }

    const [caseKey, ...empty] = Object.keys(value);
    if (!caseKey) {
      throw new FuelError(ErrorCode.INVALID_DECODE_VALUE, 'A field for the case must be provided.');
    }
    if (empty.length !== 0) {
      throw new FuelError(ErrorCode.INVALID_DECODE_VALUE, 'Only one field must be provided.');
    }
    const valueCoder = this.coders[caseKey];
    const caseIndex = Object.keys(this.coders).indexOf(caseKey);
    if (caseIndex === -1) {
      const validCases = Object.keys(this.coders)
        .map((v) => `'${v}'`)
        .join(', ');
      throw new FuelError(
        ErrorCode.INVALID_DECODE_VALUE,
        `Invalid case '${caseKey}'. Valid cases: ${validCases}.`
      );
    }

    const encodedValue = valueCoder.encode(value[caseKey]);

View on GitHub (pinned to b3f37c91ac)

Solutions

Always set exactly one variant key on the enum value object.
Validate that Object.keys(value).length === 1 before encode.
Default to a meaningful variant instead of {} when none is chosen.

Example fix

// before
enumCoder.encode({}) // no case selected

// after
enumCoder.encode({ State: [] }) // exactly one variant

Defensive patterns

Strategy: validation

Validate before calling

const keys = Object.keys(enumValue)
if (keys.length !== 1) throw new Error('enum value must have exactly one variant key')
enumCoder.encode(enumValue)

Type guard

const hasExactlyOneKey = (v: object): boolean => Object.keys(v).length === 1

Try / catch

try { enumCoder.encode(value as any) }
catch (e) { if ((e as FuelError).code === ErrorCode.INVALID_DECODE_VALUE) { /* set exactly one variant */ } throw e }

Prevention

Never pass {} as an enum value; default to a real variant.
Validate exactly-one-key before encoding.
Build enum inputs from explicit variant literals.

When it happens

Trigger: Calling enumCoder.encode({}) or passing an empty object as a Sway enum argument; building an enum input programmatically that ends up with no keys; a default/initialized-to-empty value reaching the coder.

Common situations: Form/UI state where no enum option was selected; default parameter objects; spread/merge logic that removed all keys; JSON input that omitted the variant.

Related errors

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