FuelLabs/fuels-ts · error · FuelError

BIN_FILE_NOT_FOUND

BIN_FILE_NOT_FOUND

Error message

Unable to find the following binaries on the filesystem:
 -> 'forc' at path '${systemForcPath}'
 -> 'fuel-core' at path '${systemFuelCorePath}'
Visit https://docs.fuel.network/guides/installation/ for an installation guide.

What it means

Thrown by tryFindBinaries when getSystemForc and/or getSystemFuelCore report that the 'forc' and/or 'fuel-core' CLI binaries cannot be located on the filesystem (forcError or fuelCoreError is truthy). The error aggregates which binaries are missing and their searched paths, plus a link to the install guide. metadata is the input paths object.

Source

Thrown at packages/utils/src/cli-utils/tryFindBinaries.ts:34

export const tryFindBinaries = (paths: { forcPath?: string; fuelCorePath?: string } = {}) => {
  // Ensure we can get the binary versions
  const { error: forcError, systemForcPath, systemForcVersion } = getSystemForc(paths.forcPath);

  const {
    error: fuelCoreError,
    systemFuelCorePath,
    systemFuelCoreVersion,
  } = getSystemFuelCore(paths.fuelCorePath);

  if (forcError || fuelCoreError) {
    const errors = [
      'Unable to find the following binaries on the filesystem:',
      forcError ? ` -> 'forc' at path '${systemForcPath}'` : undefined,
      fuelCoreError ? ` -> 'fuel-core' at path '${systemFuelCorePath}'` : undefined,
      `\nVisit https://docs.fuel.network/guides/installation/ for an installation guide.`,
    ];

    throw new FuelError(
      FuelError.CODES.BIN_FILE_NOT_FOUND,
      `${errors.filter(Boolean).join('\n')}`,
      { ...paths }
    );
  }

  const { systemForcIsLt, systemFuelCoreIsLt } = compareSystemVersions({
    systemForcVersion: eitherOr(systemForcVersion, '0'),
    systemFuelCoreVersion: eitherOr(systemFuelCoreVersion, '0'),
  });

  if (systemForcIsLt || systemFuelCoreIsLt) {
    const { FORC: compatibleForcVersion, FUEL_CORE: compatibleFuelCoreVersion } =
      getBuiltinVersions();

    const errors = [
      'The following binaries on the filesystem are outdated:',
      systemForcIsLt

View on GitHub (pinned to b3f37c91ac)

Solutions

Install the toolchain via the official fuelup installer: curl -fsSL https://docs.fuel.network/guides/installation/ and run 'fuelup default latest'.
Verify binaries resolve: 'which forc && which fuel-core' in the same shell/environment that runs the project.
Pass explicit forcPath/fuelCorePath to tryFindBinaries pointing at known-good executables.
In CI/Docker, ensure PATH includes the fuelup bin directory and the install step runs before tests.
Confirm the files at the searched paths are executable (chmod +x) and correct for the OS/arch.

Example fix

// before
tryFindBinaries({ forcPath: './bin/forc', fuelCorePath: './bin/fuel-core' }); // files missing

// after
// install once: curl ... | fuelup-install && fuelup default latest
tryFindBinaries(); // resolves from PATH

Defensive patterns

Strategy: validation

Validate before calling

import { execFileSync } from 'child_process';
function binExists(cmd: string): boolean {
  try { execFileSync('which', [cmd], { stdio: 'ignore' }); return true; }
  catch { return false; }
}
if (!binExists('forc') || !binExists('fuel-core')) {
  throw new Error('install fuelup: see https://docs.fuel.network/guides/installation/');
}
tryFindBinaries();

Try / catch

try {
  const { forcPath, fuelCorePath } = tryFindBinaries({ forcPath, fuelCorePath });
} catch (e) {
  if (e instanceof FuelError && e.code === FuelError.CODES.BIN_FILE_NOT_FOUND) {
    // prompt user to install fuelup, or fall back to bundled binaries
  }
  throw e;
}

Prevention

Install the toolchain with fuelup and confirm 'which forc && which fuel-core' in the running shell.
In CI/Docker, run the install step before tests and ensure PATH is exported.
Pass explicit, tested paths to tryFindBinaries instead of relying on PATH.

When it happens

Trigger: Calling tryFindBinaries({ forcPath?, fuelCorePath? }) on a machine where neither PATH lookup nor the explicitly provided path resolves to a working 'forc'/'fuel-core' executable. Triggered by fuel-core/forc launchers (e.g. during test setup or fuel-utils) when preparing to spin up a local node.

Common situations: Fresh dev environment without the Fuel toolchain installed. PATH not exported in the shell running node/test (common in CI, Docker, or non-interactive shells). Custom forcPath/fuelCorePath pointing to a nonexistent or non-executable file. Wrong architecture binary. fuel-core installed but not forc (or vice versa).

Related errors

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