firecrawl/firecrawl · error · FirecrawlError

Extract job ${extractStatus.status}. Error: ${extractStatus.

Error message

Extract job ${extractStatus.status}. Error: ${extractStatus.error}

What it means

FirecrawlError thrown by the JS SDK's extract() when polling /v1/extract/:jobId returns status 'failed' or 'cancelled'. The message embeds the server-supplied extractStatus.error and uses the status response's HTTP status as the error's statusCode. This is a terminal extract outcome reported by the server, surfaced through the SDK.

Source

Thrown at apps/js-sdk/firecrawl/src/index.backup.ts:1292

          const statusResponse: AxiosResponse = await this.getRequest(
            `${this.apiUrl}/v1/extract/${jobId}`,
            headers
          );
          extractStatus = statusResponse.data;
          if (extractStatus.status === "completed") {
            if (extractStatus.success) {
              return {
                success: true,
                data: extractStatus.data,
                warning: extractStatus.warning,
                error: extractStatus.error,
                sources: extractStatus?.sources || undefined,
              };
            } else {
              throw new FirecrawlError(`Failed to extract data. Error: ${extractStatus.error}`, statusResponse.status);
            }
          } else if (extractStatus.status === "failed" || extractStatus.status === "cancelled") {
            throw new FirecrawlError(`Extract job ${extractStatus.status}. Error: ${extractStatus.error}`, statusResponse.status);
          }
          await new Promise(resolve => setTimeout(resolve, 1000)); // Polling interval
        } while (extractStatus.status !== "completed");
      } else {
        this.handleError(response, "extract");
      }
    } catch (error: any) {
      throw new FirecrawlError(error.message, 500, error.response?.data?.details);
    }
    return { success: false, error: "Internal server error."};
  }

  /**
   * Initiates an asynchronous extract job for a URL using the Firecrawl API.
   * @param url - The URL to extract data from.
   * @param params - Additional parameters for the extract request.
   * @param idempotencyKey - Optional idempotency key for the request.
   * @returns The response from the extract operation.

View on GitHub (pinned to 656bffcc28)

Solutions

1. Inspect err.details and extractStatus.error for the server-side cause and adjust the schema/prompt accordingly.
2. Loosen or simplify the extract schema and retry.
3. Retry the call once for transient 'failed' (e.g. upstream model hiccup), but do not retry 'cancelled' unless you re-initiated it.
4. Ensure the URLs provided are reachable and contain the data the schema expects.
5. If using prompt/systemPrompt options, verify they are valid and not empty.

// Validate inputs before extracting
assert(Array.isArray(urls) && urls.every(u => /^https?:/.test(u)), 'valid urls required');
assert(!params?.schema || isValidSchema(params.schema), 'schema invalid');

function isExtractTerminal(e): e is FirecrawlError {
  return e instanceof FirecrawlError && /^Extract job (failed|cancelled)/.test(e.message);
}

try { await app.extract(urls, params); }
catch (e) {
  if (isExtractTerminal(e) && /cancelled/.test(e.message)) return;
  if (isExtractTerminal(e) && attempt < 1) { await backoff(attempt); retry; }
  else throw e;
}

When it happens

Trigger: Client calls extract(); the server accepts the job, returns an id, and during the SDK's 1s-interval polling the job transitions to 'failed' or 'cancelled'. The SDK throws FirecrawlError('Extract job <status>. Error: <server error>', statusResponse.status).

Common situations: Extract schema too strict/unsatisfiable for the page content; LLM extraction model error upstream; job cancelled via API or by the system; rate-limit/resource exhaustion marking the job failed; transient model outage surfacing as a permanent 'failed'.

Related errors

• Crawl job failed or was stopped. Status: ${statusData.status
• error.message
• Invalid schema. Schema must be either a valid Zod schema or
• Crawl job completed but no data was returned
• error

AI-assisted analysis of firecrawl/firecrawl@656bffcc28 (2026-08-12). Data as JSON: /api/errors/e35da0eca58e9e0d. Report an issue: GitHub.