FuelLabs/fuels-ts · error · FuelError

RESPONSE_BODY_EMPTY

RESPONSE_BODY_EMPTY

Error message

The response from the server is missing the body

What it means

Thrown by Provider's fetch wrapper when the HTTP response from the node has response.body === null. The SDK needs a body to parse the JSON-RPC response; a null body means the server returned a response with no content (e.g. a network error, a redirect, or a misconfigured gateway) and there is nothing to decode.

Source

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

      const signal = timeout ? AbortSignal.timeout(timeout) : undefined;

      let fullRequest: RequestInit = {
        ...request,
        signal,
        headers: { ...request?.headers, ...headers },
      };

      if (options.requestMiddleware) {
        fullRequest = await options.requestMiddleware(fullRequest);
      }

      if (Provider.ENABLE_RPC_CONSISTENCY && Provider.hasWriteOperationHappened(url)) {
        Provider.applyBlockHeight(fullRequest, url);
      }

      const response = await Provider.fetchAndProcessBlockHeight(url, fullRequest, options);
      if (response.body === null) {
        throw new FuelError(
          ErrorCode.RESPONSE_BODY_EMPTY,
          'The response from the server is missing the body',
          { timestamp: new Date().toISOString(), request, response }
        );
      }

      return response;
    }, retryOptions);
  }

  private static applyBlockHeight(request: RequestInit, url: string) {
    const normalizedUrl = this.normalizeUrl(url);

    // Apply the block height to the request
    const currentBlockHeight = Provider.currentBlockHeightCache[normalizedUrl] ?? 0;
    request.body = request.body
      ?.toString()
      .replace(/}$/, `,"extensions":{"required_fuel_block_height":${currentBlockHeight}}}`);

View on GitHub (pinned to b3f37c91ac)

Solutions

  1. Verify the provider URL points to the fuel-core GraphQL endpoint (typically http(s)://host/v1/graphql).
  2. Test the URL with curl: a healthy node returns JSON, not HTML or empty.
  3. Check intermediate proxies/gateways for body-stripping on errors; inspect response.status and headers captured in the error metadata.
  4. Ensure network connectivity to the node and that the node process is running.

Example fix

// before
const provider = new Provider('https://my-node.example.com'); // wrong path

// after — point at the actual RPC endpoint
const provider = new Provider('https://my-node.example.com/v1/graphql');

// also verify with curl:
// curl -sS -X POST https://my-node.example.com/v1/graphql -H 'content-type: application/json' -d '{"query":"{chain{latestBlock{height}}}"}'
Defensive patterns

Strategy: validation

Validate before calling

// Validate the RPC URL responds with a JSON body before constructing workflows.
async function assertRpcReachable(url: string) {
  const res = await fetch(url, {
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify({ query: '{ chain { latestBlock { height } } }' }),
  });
  if (res.body === null) throw new Error(`No response body from ${url}; check the endpoint.`);
}

Type guard

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

Try / catch

import { FuelError, ErrorCode } from '@fuel-ts/errors';
try {
  await provider.call(...);
} catch (e) {
  if (e instanceof FuelError && e.code === ErrorCode.RESPONSE_BODY_EMPTY) {
    // verify the URL/endpoint and node reachability
  }
  throw e;
}

Prevention

When it happens

Trigger: The node URL returns a 200/204 with empty body; a reverse proxy returns a response with no body (e.g. a redirect or auth challenge); the connection was closed mid-response yielding a null stream; calling Provider operations against a URL that serves an HTML page instead of the RPC endpoint.

Common situations: Wrong provider URL (pointing at a web UI, status page, or load balancer root instead of /v1/graphql); proxy/gateway strip the body on auth failure; CORS preflight in browsers returning an opaque response; node crashed mid-request; HTTP/2 reset.

Related errors

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