FuelLabs/fuels-ts · error · FuelError

ENCODE_ERROR

ENCODE_ERROR

Error message

Invalid ${this.type}. Field "${fieldName}" not present.

What it means

Thrown by StructCoder.encode() when iterating struct fields and encountering a non-Option field whose value is null or undefined. Only fields backed by OptionCoder may be null/undefined; all other field types (u32, b256, bool, str[N], etc.) must have a concrete value. The error message names the specific missing field.

Source

Thrown at packages/abi-coder/src/encoding/coders/StructCoder.ts:43

  constructor(name: string, coders: TCoders) {
    const encodedLength = Object.values(coders).reduce(
      (acc, coder) => acc + coder.encodedLength,
      0
    );
    super('struct', `struct ${name}`, encodedLength);
    this.name = name;
    this.coders = coders;
    this.#hasNestedOption = hasNestedOption(coders);
  }

  encode(value: InputValueOf<TCoders>): Uint8Array {
    return concatBytes(
      Object.keys(this.coders).map((fieldName) => {
        const fieldCoder = this.coders[fieldName];
        const fieldValue = value[fieldName];

        if (!(fieldCoder instanceof OptionCoder) && fieldValue == null) {
          throw new FuelError(
            ErrorCode.ENCODE_ERROR,
            `Invalid ${this.type}. Field "${fieldName}" not present.`
          );
        }

        return fieldCoder.encode(fieldValue);
      })
    );
  }

  decode(data: Uint8Array, offset: number): [DecodedValueOf<TCoders>, number] {
    if (!this.#hasNestedOption && data.length < this.encodedLength) {
      throw new FuelError(ErrorCode.DECODE_ERROR, `Invalid struct data size.`);
    }

    let newOffset = offset;
    const decodedValue = Object.keys(this.coders).reduce((obj, fieldName) => {
      const fieldCoder = this.coders[fieldName];

View on GitHub (pinned to b3f37c91ac)

Solutions

1. Provide a concrete value for every non-Option field before encoding.
2. If the field is genuinely nullable, change the ABI type to Option<T> so OptionCoder handles it.
3. Check for field name typos between the value object and the ABI struct definition.

Example fix

// before
structCoder.encode({ a: 1 }); // field 'b' undefined -> ENCODE_ERROR

// after
structCoder.encode({ a: 1, b: 0 });
// or change ABI to b: Option<u32>:
structCoder.encode({ a: 1, b: undefined });

function hasAllRequiredFields(value: Record<string, unknown>, requiredFields: string[]): boolean {
  return requiredFields.every(f => value[f] != null);
}

function isCompleteStruct<T extends Record<string, unknown>>(value: unknown, requiredFields: string[]): value is T {
  if (typeof value !== 'object' || value === null) return false;
  const obj = value as Record<string, unknown>;
  return requiredFields.every(f => f in obj && obj[f] != null);
}

When it happens

Trigger: Encoding a struct object where a required field (e.g. u32, b256) is undefined or null. Constructing a struct from partial data without setting all fields. A field name typo in the object causing the actual field to remain undefined.

Common situations: Optional application data not fully populated before encoding. An API response with missing keys passed directly to the encoder. The ABI struct definition has more non-Option fields than the client provides.

Related errors

• ENCODE_ERROR
• ENCODE_ERROR
• ENCODE_ERROR
• INVALID_DECODE_VALUE
• ENCODE_ERROR

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