FuelLabs/fuels-ts · error · FuelError

PARSE_FAILED

PARSE_FAILED

Error message

Failed to parse the error object. The required 'code' property is missing.

What it means

Thrown by FuelError.parse() when the input object has no `code` property. parse() expects a serialized FuelError shape; `code` is the discriminator it uses to reconstruct the error, so its absence means the input was never a FuelError. This guards the parser against plain Error objects, network error bodies, and arbitrary JSON.

Source

Thrown at packages/errors/src/fuel-error.ts:15

import { versions } from '@fuel-ts/versions';

import { ErrorCode } from './error-codes';

export class FuelError extends Error {
  static readonly CODES = ErrorCode;
  readonly VERSIONS = versions;
  readonly metadata: Record<string, unknown>;
  readonly rawError: unknown;

  static parse(e: unknown) {
    const error = e as FuelError;

    if (error.code === undefined) {
      throw new FuelError(
        ErrorCode.PARSE_FAILED,
        "Failed to parse the error object. The required 'code' property is missing."
      );
    }

    const enumValues = Object.values(ErrorCode);
    const codeIsKnown = enumValues.includes(error.code);

    if (!codeIsKnown) {
      throw new FuelError(
        ErrorCode.PARSE_FAILED,
        `Unknown error code: ${error.code}. Accepted codes: ${enumValues.join(', ')}.`
      );
    }

    return new FuelError(error.code, error.message, error.metadata, error.rawError);
  }

View on GitHub (pinned to b3f37c91ac)

Solutions

Guard the input before parsing: only call parse() when the object looks like a FuelError.
Use `instanceof FuelError` first and skip parse() for already-typed errors.
When receiving errors over the wire, confirm the source serializes with `code` before calling parse().

Example fix

// before
const err = FuelError.parse(maybeError);
// after — narrow first
function toFuelError(e: unknown) {
  if (e instanceof FuelError) return e;
  if (e && typeof e === 'object' && 'code' in e && typeof (e as any).code === 'string') {
    return FuelError.parse(e);
  }
  return new FuelError(FuelError.CODES.UNKNOWN, (e as Error)?.message ?? 'Unknown error');
}

Defensive patterns

Strategy: type-guard

Validate before calling

const looksLikeFuelError = (e: unknown): boolean =>
  !!e && typeof e === 'object' && 'code' in e && typeof (e as any).code !== 'undefined';

Type guard

import { ErrorCode, FuelError } from '@fuel-ts/errors';
function isFuelErrorShape(e: unknown): e is { code: ErrorCode; message: string; metadata?: unknown } {
  return !!e && typeof e === 'object' && 'code' in e;
}

Try / catch

try {
  return FuelError.parse(input);
} catch (e) {
  if (e instanceof FuelError && e.code === FuelError.CODES.PARSE_FAILED) {
    return new FuelError(FuelError.CODES.UNKNOWN, String((input as Error)?.message ?? input));
  }
  throw e;
}

Prevention

Check `instanceof FuelError` before calling parse().
Only feed parse() objects you serialized from a FuelError.
Never pipe arbitrary caught values into parse(); narrow first.

When it happens

Trigger: Calling `FuelError.parse(e)` on a plain `Error`, an HTTP error response body, a `TypeError`, or any object that does not carry a `code` field.

Common situations: Generic catch blocks that funnel every caught value through FuelError.parse; deserializing error JSON from a server that wraps errors differently; passing the result of `.toJSON()` on a non-Fuel error.

Understand the failure class

Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

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