fix(api): treat empty OPENAI_API_KEY/BASE_URL as unset (#4083) by SomSamantray · Pull Request #4438 · firecrawl/firecrawl

SomSamantray · 2026-08-28T05:14:36Z

Summary

Self-hosted deployments that pass OPENAI_API_KEY / OPENAI_BASE_URL through docker-compose ${VAR} passthrough receive empty strings when the variables are unset in .env. The config schema accepted "", so createOpenAI received a literal empty apiKey/baseURL, and formats: ["json"] requests failed with Failed to parse URL from /responses — returning success: true with no json field while still billing credits.

Fixes #4083.

What changed

emptyStringAsUndefined keeps its exact-"" semantics. A new emptyOrWhitespaceStringAsUndefined helper also coerces whitespace-only strings, and is used only where a whitespace-only value is never meaningful: OPENAI_API_KEY, OPENAI_BASE_URL, and the FIREBRAIN_TRACKS_* pair (which already had inline trim behavior).
Credential and URL fields that must fail closed at boot (FIREBILL_URL, FIREBILL_SECRET, KEYLESS_CONVERSION_HMAC_SECRET, MCP_DELEGATED_CREDENTIAL_SECRET, etc.) are untouched — a whitespace-only FIREBILL_URL still fails validation at startup instead of silently disabling billing routing.
Config-layer coercion alone was not enough: @ai-sdk/openai re-reads process.env at request time via loadApiKey / loadOptionalSetting when the createOpenAI option is undefined. So config.ts now deletes OPENAI_API_KEY / OPENAI_BASE_URL from process.env after parsing when they were coerced to undefined, and warns at boot. The SDK then raises the intended missing-key error and falls back to the default base URL.
The regression test moved into src/__tests__/snips/v2/ so CI's pnpm harness pnpm test:snips lane executes it, and now also asserts process.env deletion, FIREBRAIN behavior, and whitespace-padded passthrough.

Verification

vitest run src/__tests__/snips/v2/config.test.ts — 8/8 pass (empty, whitespace-only, real, unset, process.env deletion, FIREBRAIN, padded passthrough).
Empirically verified against the installed @ai-sdk/openai 3.0.71: before, env "" produced request URL "/responses" (the ERR_INVALID_URL failure); after, the resolved URL uses the default https://api.openai.com/v1 base.
vitest run src/search/highlights.test.ts src/lib/threat-protection/config.test.ts — pass (45 tests total).
tsc --noEmit — no errors in changed files (remaining repo-wide errors are pre-existing @mendable/firecrawl-rs native-module resolution, built by CI).

Impact

No migration, no deployment changes, no SDK/API surface changes.
Operators with a set-but-empty OpenAI key now see a boot warning instead of silent per-request failures that still bill credits.
Behavior for all other emptyStringAsUndefined users is unchanged (exact-"" semantics preserved).

Summary by cubic

Fixes self-hosted deployments where docker-compose ${VAR} passthrough exposes empty OPENAI_API_KEY and OPENAI_BASE_URL strings. Empty and whitespace-only values are now treated as unset, so @ai-sdk/openai raises the intended missing-key error and falls back to the default base URL instead of failing per-request and still billing credits.

Bug Fixes

Added emptyOrWhitespaceStringAsUndefined for OPENAI_* and FIREBRAIN_TRACKS_* vars; real values are trimmed so padded keys and URLs reach the SDK normalized.
Deletes coerced-to-undefined OpenAI keys from process.env after config parse, since the SDK re-reads env at request time. Boot warnings differentiate: an empty key makes the OpenAI provider unavailable, while an empty base URL falls back to the default.
Other fail-closed fields (FIREBILL_*, KEYLESS_*, MCP_DELEGATED_*) keep exact-"" semantics, so whitespace-only values still fail validation at startup.
Regression tests moved to src/__tests__/snips/v2/ so CI's snips lane runs them; coverage includes empty, whitespace-only, real, unset, trimming, and process.env deletion cases.

^{Written for commit 0fdb590. Summary will update on new commits.}

Docker Compose passes unset .env vars through as empty strings. The config schema kept them, so createOpenAI received apiKey:"" and baseURL:"", producing "Failed to parse URL from /responses" and a silent json-format failure that still billed credits. Apply the existing emptyStringAsUndefined helper (now also trimming whitespace-only values) to OPENAI_API_KEY and OPENAI_BASE_URL so the intended missing-key error and default base URL apply. Adds a regression test covering empty, whitespace-only, real, and unset values.

…wl#4083) Review found the config-layer coercion alone was a no-op: @ai-sdk/openai re-reads process.env at request time via loadApiKey/loadOptionalSetting when the createOpenAI option is undefined, so docker-compose's '' was resurrected and the 'Failed to parse URL from /responses' failure persisted. - Delete OPENAI_API_KEY/OPENAI_BASE_URL from process.env after parse when coerced to undefined, so the SDK env fallback sees unset and the intended missing-key error / default base URL apply. Warn at boot when a set-but-empty key is dropped (console.warn: importing the winston logger here would create a config <-> logger cycle). - Keep emptyStringAsUndefined at exact-'' semantics and add emptyOrWhitespaceStringAsUndefined for the fields that need it (OPENAI_*, FIREBRAIN_TRACKS_*), so whitespace-only FIREBILL_URL and secrets still fail closed at boot instead of silently disabling billing. - Move the regression test into src/__tests__/snips/v2/ so CI's 'pnpm harness pnpm test:snips' lane actually executes it, and assert process.env deletion, FIREBRAIN behavior, and padded passthrough.

cubic-dev-ai

All reported issues were addressed across 2 files

_{Reply with feedback, questions, or to request a fix.

Fix all with cubic | Re-trigger cubic}

- Trim OPENAI_API_KEY/OPENAI_BASE_URL values so whitespace-padded keys and URLs are normalized before reaching createOpenAI (a padded key would otherwise auth with trailing spaces and 401 with no warning). - Differentiate boot warnings: an empty API key makes the OpenAI provider unavailable; an empty base URL merely falls back to the default https://api.openai.com/v1 (the provider still works when a key is present). - Restore FIREBRAIN_TRACKS_URL/API_KEY in the config test afterAll so the env-mutation test does not leak into other tests.

SomSamantray · 2026-08-28T05:32:30Z

All 3 review findings addressed in 0fdb590:

P2 (config.ts:600) — Boot warnings now differentiate: an empty OPENAI_API_KEY makes the provider unavailable; an empty OPENAI_BASE_URL only falls back to the default https://api.openai.com/v1 (provider still works when a key is present).
P3 (config.test.ts) — FIREBRAIN_TRACKS_URL / FIREBRAIN_TRACKS_API_KEY are now captured and restored in afterAll, matching the audio-routing pattern; no env leak.
P3 (config.ts) — OPENAI_API_KEY / OPENAI_BASE_URL are now z.string().trim()-normalized, so whitespace-padded values are trimmed before reaching createOpenAI (verified: generic-ai passes the trimmed config value; the SDK uses it directly).

Verified: 8/8 config tests pass (incl. trimmed-padded assertions), 45 tests total, typecheck clean for changed files.

SomSamantray · 2026-08-28T05:35:33Z

CI status

All code-side checks are green and all review feedback is resolved. The PR is blocked only on maintainer-side approvals that an external contributor cannot perform:

Server Test Suite (test-server.yml) and Audit NPM Packages — triggered but waiting for a maintainer to approve the workflow run for this fork PR (action_required). Approving requires admin rights (verified 403).
Vercel deployment — "Authorization required to deploy"; a maintainer must click Approve and deploy in Vercel for the fork PR.
Human review — no maintainer review yet.

Resolved this round:

cubic AI review: all 3 findings addressed (differentiated boot warnings, FIREBRAIN env restore in tests, trim-normalized OpenAI values); cubic confirms "All reported issues were addressed".
Contributor trust: ✅ · Superagent Security Scan: ✅ · Vercel Agent Review: neutral/skipped.

Once a maintainer approves the workflow runs, the real test suite will execute against 0fdb590.

cubic-dev-ai

0 issues found across 2 files (changes from recent commits).

_{Re-trigger cubic}

SomSamantray added 3 commits August 28, 2026 09:36

refactor(api): reuse emptyStringAsUndefined for FIREBRAIN_TRACKS vars

9b81978

cubic-dev-ai Bot reviewed Aug 28, 2026

View reviewed changes

Comment thread apps/api/src/config.ts Outdated

Comment thread apps/api/src/__tests__/snips/v2/config.test.ts

Comment thread apps/api/src/config.ts Outdated

cubic-dev-ai Bot approved these changes Aug 28, 2026

View reviewed changes

Navigation Menu

Uh oh!

fix(api): treat empty OPENAI_API_KEY/BASE_URL as unset (#4083) - #4438

fix(api): treat empty OPENAI_API_KEY/BASE_URL as unset (#4083)#4438
SomSamantray wants to merge 4 commits into
firecrawl:mainfrom
SomSamantray:fix/4083-empty-openai-env

SomSamantray commented Aug 28, 2026 •

edited by cubic-dev-ai Bot

Loading

Uh oh!

cubic-dev-ai Bot left a comment •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

SomSamantray commented Aug 28, 2026

Uh oh!

SomSamantray commented Aug 28, 2026

Uh oh!

cubic-dev-ai Bot left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

SomSamantray commented Aug 28, 2026 • edited by cubic-dev-ai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

What changed

Verification

Impact

Summary by cubic

Uh oh!

cubic-dev-ai Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

SomSamantray commented Aug 28, 2026

Uh oh!

SomSamantray commented Aug 28, 2026

CI status

Uh oh!

cubic-dev-ai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

SomSamantray commented Aug 28, 2026 •

edited by cubic-dev-ai Bot

Loading

cubic-dev-ai Bot left a comment •

edited

Loading