What causes "Failed to fetch latest fuels version." in FuelLabs/fuels-ts?

Ensure outbound HTTPS to registry.npmjs.org is permitted from the build environment.

FuelLabs/fuels-ts · warning · Error

Failed to fetch latest fuels version.

Error message

Failed to fetch latest fuels version.

What it means

A plain Error (not a FuelError) thrown by getLatestFuelsVersion when the npm registry fetch loses a 3-second race against a setTimeout and resolves to null. The function only throws when the timeout wins; a successful fetch returns the version. The result is used for version-bump hints, so this failure is non-fatal to builds and should be caught by callers.

Source

Thrown at packages/fuels/src/cli/utils/getLatestFuelsVersion.ts:18

import { checkAndLoadCache, saveToCache } from './fuelsVersionCache';

export const getLatestFuelsVersion = async (): Promise<string | undefined> => {
  const cachedVersion = checkAndLoadCache();
  if (cachedVersion) {
    return cachedVersion;
  }

  const data: { version: string } | null = await Promise.race([
    new Promise((_, reject) => {
      // eslint-disable-next-line prefer-promise-reject-errors
      setTimeout(() => reject(null), 3000);
    }),
    fetch('https://registry.npmjs.org/fuels/latest').then((response) => response.json()),
  ]);

  if (!data) {
    throw new Error('Failed to fetch latest fuels version.');
  }

  const version = data.version as string;

  saveToCache(version);

  return version;
};

View on GitHub (pinned to b3f37c91ac)

Solutions

Ensure outbound HTTPS to registry.npmjs.org is permitted from the build environment.
Configure HTTP(S)_PROXY if behind a corporate proxy.
Wrap the call in try-catch and treat undefined as 'no version hint'.
Pre-warm the version cache (fuelsVersionCache) in environments with intermittent connectivity.

Example fix

// before
const latest = await getLatestFuelsVersion();
// after — tolerate the hint being unavailable
let latest: string | undefined;
try {
  latest = await getLatestFuelsVersion();
} catch {
  latest = undefined;
}

Defensive patterns

Strategy: fallback

Validate before calling

import { checkAndLoadCache } from './fuelsVersionCache';
const safeGetLatest = async (): Promise<string | undefined> => checkAndLoadCache() ?? undefined;

Try / catch

let latest: string | undefined;
try {
  latest = await getLatestFuelsVersion();
} catch {
  latest = undefined; // version hint is non-essential
}

Prevention

Treat the latest-version hint as optional; never block builds on it.
Whitelist registry.npmjs.org in CI network policy.
Cache the version locally to avoid repeated fetches.

When it happens

Trigger: Calling getLatestFuelsVersion when the network is slow, offline, behind a restrictive proxy, or when registry.npmjs.org is unreachable within 3s.

Common situations: Air-gapped CI, corporate firewall/proxy blocking npm registry, slow mobile link, transient npm outage.

Related errors

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