FuelLabs/fuels-ts · error · FuelError

MISSING_REQUIRED_PARAMETER

MISSING_REQUIRED_PARAMETER

Error message

You must provide a privateKey via config.privateKey or env PRIVATE_KEY

What it means

Thrown by createWallet when neither a privateKey argument nor a PRIVATE_KEY environment variable is available. The deploy command needs a funded signer to submit transactions, so the CLI refuses to proceed without one rather than silently using an empty key.

Source

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

import { Wallet, Provider } from '@fuel-ts/account';
import { FuelError } from '@fuel-ts/errors';

export async function createWallet(providerUrl: string, privateKey?: string) {
  let pvtKey: string;

  if (privateKey) {
    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 {

View on GitHub (pinned to b3f37c91ac)

Solutions

Export PRIVATE_KEY in the shell or CI secret before running fuels: `export PRIVATE_KEY=0x...`.
Load your .env first (e.g. `dotenv -e .env -- fuels deploy`).
Set `privateKey` in fuels.config.ts (not recommended for shared repos).
Pass the key via the CLI flag if the command supports it.

Example fix

// before
fuels deploy   # PRIVATE_KEY unset
// after
export PRIVATE_KEY=0x$(cat ~/.fuel/private-key)
fuels deploy

Defensive patterns

Strategy: validation

Validate before calling

function resolvePrivateKey(arg?: string): string {
  const key = arg ?? process.env.PRIVATE_KEY;
  if (!key) {
    throw new Error('PRIVATE_KEY is not set; export it or pass via config.privateKey');
  }
  return key;
}

Type guard

const hasPrivateKey = (cfg?: { privateKey?: string }): cfg is { privateKey: string } =>
  !!cfg && typeof cfg.privateKey === 'string' && cfg.privateKey.length > 0;

Prevention

Set PRIVATE_KEY in your CI secrets and load it before invoking fuels.
Validate required env at app startup with a fail-fast check.
Never commit the key to fuels.config.ts; use env injection.

When it happens

Trigger: Running `fuels deploy` (or calling createWallet directly) with no --privateKey and no PRIVATE_KEY in the environment, and no privateKey in the fuels config.

Common situations: CI/CD that forgot to set PRIVATE_KEY, local .env not loaded by the CLI, deploy from a fresh shell, config missing the privateKey field.

Related errors

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