{"record":{"id":"73ca3a05bb0eb951","repo":"FuelLabs/fuels-ts","slug":"bin-file-not-found-73ca3a","errorCode":"BIN_FILE_NOT_FOUND","errorMessage":"Unable to find the following binaries on the filesystem:\n -> 'forc' at path '${systemForcPath}'\n -> 'fuel-core' at path '${systemFuelCorePath}'\nVisit https://docs.fuel.network/guides/installation/ for an installation guide.","messagePattern":"Unable to find the following binaries on the filesystem:\n -> 'forc' at path '(.+?)'\n -> 'fuel-core' at path '(.+?)'\nVisit https://docs\\.fuel\\.network/guides/installation/ for an installation guide\\.","errorType":"exception","errorClass":"FuelError","httpStatus":null,"severity":"error","filePath":"packages/utils/src/cli-utils/tryFindBinaries.ts","lineNumber":34,"sourceCode":"export const tryFindBinaries = (paths: { forcPath?: string; fuelCorePath?: string } = {}) => {\n  // Ensure we can get the binary versions\n  const { error: forcError, systemForcPath, systemForcVersion } = getSystemForc(paths.forcPath);\n\n  const {\n    error: fuelCoreError,\n    systemFuelCorePath,\n    systemFuelCoreVersion,\n  } = getSystemFuelCore(paths.fuelCorePath);\n\n  if (forcError || fuelCoreError) {\n    const errors = [\n      'Unable to find the following binaries on the filesystem:',\n      forcError ? ` -> 'forc' at path '${systemForcPath}'` : undefined,\n      fuelCoreError ? ` -> 'fuel-core' at path '${systemFuelCorePath}'` : undefined,\n      `\\nVisit https://docs.fuel.network/guides/installation/ for an installation guide.`,\n    ];\n\n    throw new FuelError(\n      FuelError.CODES.BIN_FILE_NOT_FOUND,\n      `${errors.filter(Boolean).join('\\n')}`,\n      { ...paths }\n    );\n  }\n\n  const { systemForcIsLt, systemFuelCoreIsLt } = compareSystemVersions({\n    systemForcVersion: eitherOr(systemForcVersion, '0'),\n    systemFuelCoreVersion: eitherOr(systemFuelCoreVersion, '0'),\n  });\n\n  if (systemForcIsLt || systemFuelCoreIsLt) {\n    const { FORC: compatibleForcVersion, FUEL_CORE: compatibleFuelCoreVersion } =\n      getBuiltinVersions();\n\n    const errors = [\n      'The following binaries on the filesystem are outdated:',\n      systemForcIsLt","sourceCodeStart":16,"sourceCodeEnd":52,"githubUrl":"https://github.com/FuelLabs/fuels-ts/blob/b3f37c91aca4aa9d5e4c0d3967f66237190826ea/packages/utils/src/cli-utils/tryFindBinaries.ts#L16-L52","documentation":"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.","triggerScenarios":"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.","commonSituations":"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).","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."],"exampleFix":"// before\ntryFindBinaries({ forcPath: './bin/forc', fuelCorePath: './bin/fuel-core' }); // files missing\n\n// after\n// install once: curl ... | fuelup-install && fuelup default latest\ntryFindBinaries(); // resolves from PATH","handlingStrategy":"validation","validationCode":"import { execFileSync } from 'child_process';\nfunction binExists(cmd: string): boolean {\n  try { execFileSync('which', [cmd], { stdio: 'ignore' }); return true; }\n  catch { return false; }\n}\nif (!binExists('forc') || !binExists('fuel-core')) {\n  throw new Error('install fuelup: see https://docs.fuel.network/guides/installation/');\n}\ntryFindBinaries();","typeGuard":null,"tryCatchPattern":"try {\n  const { forcPath, fuelCorePath } = tryFindBinaries({ forcPath, fuelCorePath });\n} catch (e) {\n  if (e instanceof FuelError && e.code === FuelError.CODES.BIN_FILE_NOT_FOUND) {\n    // prompt user to install fuelup, or fall back to bundled binaries\n  }\n  throw e;\n}","preventionTips":["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."],"tags":["cli","binaries","environment","fuel-core","forc"],"backgroundTag":null,"analyzedSha":"b3f37c91aca4aa9d5e4c0d3967f66237190826ea","analyzedAt":"2026-08-12T20:30:56.448Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}