FuelLabs/fuels-ts · error · FuelError

INVALID_URL

INVALID_URL

Error message

Invalid URL provided.

What it means

Thrown by Provider.extractBasicAuth when the constructor's URL argument cannot be parsed by the URL constructor (it throws). This happens before any network call, during provider construction. The original parse error is attached as the cause, and the malformed url is included in metadata.

Source

Thrown at packages/account/src/providers/provider.ts:718

        this.cache = new ResourceCache(resourceCacheTTL);
      } else {
        this.cache = undefined;
      }
    } else {
      this.cache = new ResourceCache(DEFAULT_RESOURCE_CACHE_TTL);
    }
  }

  private static extractBasicAuth(url: string): {
    url: string;
    urlWithoutAuth: string;
    headers: ProviderOptions['headers'];
  } {
    let parsedUrl: URL;
    try {
      parsedUrl = new URL(url);
    } catch (error) {
      throw new FuelError(FuelError.CODES.INVALID_URL, 'Invalid URL provided.', { url }, error);
    }

    const username = parsedUrl.username;
    const password = parsedUrl.password;
    const urlWithoutAuth = `${parsedUrl.origin}${parsedUrl.pathname}`;
    if (!(username && password)) {
      return { url, urlWithoutAuth: url, headers: undefined };
    }

    return {
      url,
      urlWithoutAuth,
      headers: { Authorization: `Basic ${btoa(`${username}:${password}`)}` },
    };
  }

  /**
   * Initialize Provider async stuff

View on GitHub (pinned to b3f37c91ac)

Solutions

1. Ensure the URL has an explicit scheme: 'http://localhost:4000/v1/graphql'.
2. Trim whitespace and validate the env value before constructing the Provider.
3. Wrap construction in a try/catch to surface INVALID_URL with the offending value.
4. Use new URL(url) yourself first to fail with a clearer message during config loading.

Example fix

// before
const provider = new Provider(process.env.NODE_URL); // e.g. 'localhost:4000'

// after — normalize at config time
const raw = (process.env.NODE_URL ?? '').trim();
const url = /^https?:\/\//.test(raw) ? raw : `http://${raw}`;
new URL(url); // throws early if still invalid
const provider = new Provider(url);

function normalizeProviderUrl(raw: string): string {
  const trimmed = (raw ?? '').trim();
  const withScheme = /^https?:\/\//i.test(trimmed) ? trimmed : `http://${trimmed}`;
  new URL(withScheme); // throws if still invalid
  return withScheme;
}

function isValidUrl(url: string): boolean {
  try { new URL(url); return true; } catch { return false; }
}

import { FuelError } from '@fuel-ts/errors';
try {
  const provider = new Provider(url);
} catch (e) {
  if (e instanceof FuelError && e.code === FuelError.CODES.INVALID_URL) {
    // prompt for a corrected URL with explicit scheme
  }
  throw e;
}

When it happens

Trigger: Constructing new Provider(url) with a string that is not a valid absolute URL: missing protocol, stray characters, whitespace, a relative path, or undefined; passing a URL without a scheme (e.g. 'localhost:4000'); passing a URL with embedded credentials malformed.

Common situations: Forgetting the http(s):// scheme when reading a URL from env (e.g. process.env.NODE_URL === 'localhost:4000'); trailing slash/space from env var; copy-paste introduced a unicode character; .env var was undefined and coerced to 'undefined'.

Related errors

• INVALID_TTL
• UNSUPPORTED_ENCODING_VERSION
• INVALID_INPUT_PARAMETERS
• ERROR_BUILDING_BLOCK_EXPLORER_URL
• INVALID_INPUT_PARAMETERS

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