FuelLabs/fuels-ts · error · FuelError

CONNECTION_REFUSED

CONNECTION_REFUSED

Error message

Couldn't connect to the node at "${providerUrl}". Check that you've got a node running at the config's providerUrl or set autoStartFuelCore to true.

What it means

Thrown by createWallet when `new Provider(providerUrl).init()` fails with an EADDRNOTAVAIL or ECONNREFUSED cause. These socket-level errors mean no Fuel node is listening at the configured providerUrl, so the deploy cannot fetch chain state or submit transactions.

Source

Thrown at packages/fuels/src/cli/commands/deploy/createWallet.ts:26

    pvtKey = privateKey;
  } else if (process.env.PRIVATE_KEY) {
    pvtKey = process.env.PRIVATE_KEY;
  } else {
    throw new FuelError(
      FuelError.CODES.MISSING_REQUIRED_PARAMETER,
      'You must provide a privateKey via config.privateKey or env PRIVATE_KEY'
    );
  }

  try {
    const provider = new Provider(providerUrl);
    await provider.init(); // can probably be removed

    return Wallet.fromPrivateKey(pvtKey, provider);
  } catch (e) {
    const error = e as Error & { cause?: { code: string } };
    if (/EADDRNOTAVAIL|ECONNREFUSED/.test(error.cause?.code ?? '')) {
      throw new FuelError(
        FuelError.CODES.CONNECTION_REFUSED,
        `Couldn't connect to the node at "${providerUrl}". Check that you've got a node running at the config's providerUrl or set autoStartFuelCore to true.`
      );
    } else {
      throw error;
    }
  }
}

View on GitHub (pinned to b3f37c91ac)

Solutions

1. Start a local fuel-core node or point providerUrl at a running one.
2. Set `autoStartFuelCore: true` in fuels.config.ts so the CLI launches a node for you.
3. Verify the URL and port: curl the /health endpoint before deploying.
4. Check that Docker/containerized fuel-core publishes the port you configured.

Example fix

// before — fuels.config.ts
export default createConfig({ providerUrl: 'http://127.0.0.1:4000', autoStartFuelCore: false });
// after
export default createConfig({ providerUrl: 'http://127.0.0.1:4000', autoStartFuelCore: true });

async function assertNodeReachable(url: string): Promise<void> {
  const res = await fetch(url + '/health', { signal: AbortSignal.timeout(3000) });
  if (!res.ok) throw new Error(`node not reachable at ${url}`);
}

const isConnectionError = (e: unknown): boolean => {
  const code = (e as any)?.cause?.code ?? (e as any)?.code;
  return /EADDRNOTAVAIL|ECONNREFUSED|ENOTFOUND/.test(String(code));
};

for (let attempt = 0; attempt < 3; attempt++) {
  try {
    return await createWallet(providerUrl, privateKey);
  } catch (e) {
    if (!isConnectionError(e) || attempt === 2) throw e;
  }
}

When it happens

Trigger: Running deploy against a providerUrl where fuel-core is not running, is on a different port, or is unreachable; localhost URL while fuel-core was never started.

Common situations: Forgot to start fuel-core locally, wrong port in fuels.config.ts, Docker container not exposed on the expected port, network/firewall blocking the node, autoStartFuelCore left false.

Related errors

• CONNECTION_REFUSED
• Version '${fuelCoreVersion}' not found\n at ${pkgUrl}
• MISSING_REQUIRED_PARAMETER
• Failed to fetch latest fuels version.
• BIN_FILE_NOT_FOUND

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