FuelLabs/fuels-ts · critical · FuelError

INVALID_PROVIDER

INVALID_PROVIDER

Error message

Error initializing Fuel Connector

What it means

Thrown by Fuel.initialize when either setDefaultConnector or setupConnectorListener throws during startup. The Fuel connector manager wraps the underlying failure in a single INVALID_PROVIDER error because the wallet-connector subsystem cannot operate without a healthy default connector and event wiring. It is a fatal init-time error: the connector manager is unusable until fixed.

Source

Thrown at packages/account/src/connectors/fuel.ts:111

    this.setMaxListeners(1_000);
    // Set all connectors
    this._connectors = config.connectors ?? [];
    // Set the target object to listen for global events
    this._targetObject = this.getTargetObject(config.targetObject);
    // Set default storage
    this._storage = config.storage === undefined ? this.getStorage() : config.storage;
    // Setup all methods
    this.setupMethods();
    this._initializationPromise = this.initialize();
  }

  private async initialize(): Promise<void> {
    try {
      const connectResponse = this.setDefaultConnector();
      this._targetUnsubscribe = this.setupConnectorListener();
      await connectResponse;
    } catch (error) {
      throw new FuelError(ErrorCode.INVALID_PROVIDER, 'Error initializing Fuel Connector');
    }
  }

  public async init(): Promise<Fuel> {
    await this._initializationPromise;
    return this;
  }

  /**
   * Return the target object to listen for global events.
   */
  private getTargetObject(targetObject?: TargetObject): TargetObject | null {
    if (targetObject) {
      return targetObject;
    }
    if (typeof window !== 'undefined') {
      return window;
    }

View on GitHub (pinned to b3f37c91ac)

Solutions

1. Pass at least one connector in config.connectors and ensure the runtime has the matching global event source the connector listens to.
2. Check that config.storage is a valid Storage-like object (or omit it to use the default) and that persisted connector state is not corrupt.
3. Wrap `await fuel.init()` in try/catch, log the inner error, and degrade to a non-connector flow when initialization fails in SSR/no-extension contexts.

Example fix

// before
const fuel = new Fuel({ connectors: [myConnector] });
await fuel.init();

// after
const fuel = new Fuel({ connectors: [myConnector], storage: localStorage });
try {
  await fuel.init();
} catch (e) {
  if (e.code === ErrorCode.INVALID_PROVIDER) {
    // fall back to direct provider/wallet flow
  } else throw e;
}

// Pre-flight: ensure at least one connector and a usable target object exist
function canInitFuel(config: { connectors?: unknown[]; targetObject?: any }): boolean {
  return (config.connectors?.length ?? 0) > 0;
}

function hasConnectors(config: { connectors?: FuelConnector[] }): config is { connectors: FuelConnector[] } {
  return Array.isArray(config.connectors) && config.connectors.length > 0;
}

try {
  await fuel.init();
} catch (e) {
  if (e instanceof FuelError && e.code === ErrorCode.INVALID_PROVIDER) {
    // log inner cause, fall back to a direct Provider/Wallet flow
  } else throw e;
}

When it happens

Trigger: Constructing new Fuel({ connectors, storage, targetObject }) where setDefaultConnector throws (e.g. no connectors passed, storage inaccessible, or the chosen default connector fails to load), or setupConnectorListener throws because the target object (window/global event source) is missing or malformed.

Common situations: Running in an environment without the expected wallet-injection global (SSR, a frame without the extension), passing an empty connectors array, a corrupted storage entry for the saved connector name, or a version mismatch between the SDK and the injected connector.

Related errors

• MISSING_CONNECTOR
• MISSING_CONNECTOR
• CHAIN_INFO_CACHE_EMPTY

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