FuelLabs/fuels-ts · error · FuelError

CHAIN_INFO_CACHE_EMPTY

CHAIN_INFO_CACHE_EMPTY

Error message

Provider chain info cache is empty. Please make sure to initialize the `Provider` properly by running `new Provider()`

What it means

Thrown by ScriptInvocationScope.buildScriptRequest() when provider.getChain() returns a falsy chain info cache. In practice this is effectively dead code: getChain() internally calls init() which fetches and populates Provider.chainInfoCache, and the source carries a TODO to remove this check because the Provider already guards it. It would only fire for a hand-rolled/mock Provider whose getChain() returns undefined, or if fetchChainAndNodeInfo() silently failed to populate the cache.

Source

Thrown at packages/script/src/script-invocation-scope.ts:28

  TReturn = any,
> extends FunctionInvocationScope<TArgs, TReturn> {
  scriptRequest!: ScriptRequest<TArgs, TReturn>;

  protected override async updateScriptRequest() {
    if (!this.scriptRequest) {
      await this.buildScriptRequest();
    }

    this.transactionRequest.setScript(this.scriptRequest, this.args);
  }

  private async buildScriptRequest() {
    const programBytes = (this.program as AbstractScript).bytes;
    const chainInfoCache = await (this.program.provider as Provider).getChain();

    // TODO: Remove this error since it is already handled on Provider class
    if (!chainInfoCache) {
      throw new FuelError(
        FuelError.CODES.CHAIN_INFO_CACHE_EMPTY,
        'Provider chain info cache is empty. Please make sure to initialize the `Provider` properly by running `new Provider()`'
      );
    }

    this.scriptRequest = new ScriptRequest(
      programBytes,
      (args: TArgs) => this.func.encodeArguments(args),
      () => [] as unknown as TReturn
    );
  }
}

View on GitHub (pinned to b3f37c91ac)

Solutions

Construct a real Provider with a reachable node URL: const provider = await Provider.create(url) (or new Provider(url) then await provider.init()).
In tests, mock getChain() to return a valid ChainInfo object (chainInfoCache populated) rather than undefined.
Confirm network connectivity to the node before instantiating the Script.

Defensive patterns

Strategy: validation

Validate before calling

// Ensure the Provider is initialized against a reachable node before binding a Script.
const provider = await Provider.create(nodeUrl); // or new Provider(nodeUrl) then await provider.init();
if (!(await provider.getChain())) {
  throw new Error('Provider chain info unavailable; check node URL and connectivity.');
}

Try / catch

try {
  await script.functions.main().call();
} catch (e) {
  if (e instanceof FuelError && e.code === FuelError.CODES.CHAIN_INFO_CACHE_EMPTY) {
    // re-init the provider / verify node reachability, then retry
    await provider.init();
  } else throw e;
}

Prevention

Use Provider.create(url) (or call provider.init()) before passing the provider to a Script.
In tests, mock getChain() to return a valid ChainInfo, not undefined.
Confirm the node URL is reachable before instantiating SDK objects.

When it happens

Trigger: Calling script functions on a Script bound to a mock Provider whose getChain() resolves to undefined; a Provider whose init()/fetchChainAndNodeInfo failed without throwing; an incompletely faked Provider in tests.

Common situations: Unit tests stubbing Provider.getChain to return undefined; a Provider constructed against an unreachable node whose chain fetch silently returned nothing (usually a different error is thrown first).

Related errors

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