Skip to content

fix(hono): change syncFacilitatorOnStart default to false for serverless compatibility#2219

Closed
lau90eth wants to merge 1 commit into
x402-foundation:mainfrom
lau90eth:fix/hono-sync-clean
Closed

fix(hono): change syncFacilitatorOnStart default to false for serverless compatibility#2219
lau90eth wants to merge 1 commit into
x402-foundation:mainfrom
lau90eth:fix/hono-sync-clean

Conversation

@lau90eth
Copy link
Copy Markdown

@lau90eth lau90eth commented May 7, 2026

Fixes #2157

Problem

paymentMiddleware() had syncFacilitatorOnStart: true as default, causing cold-start timeouts on serverless/edge environments (Cloudflare Workers, AWS Lambda).

On every cold isolate, the middleware would block the first request while fetching facilitator support data via getSupported(), producing 10–15s latencies that caused discovery probes (e.g. x402scan) to time out and mark routes as invalid.

Root cause

The accepts and extensions data needed to emit a 402 response is already known from route configuration — facilitator initialization is only required at verify/settle time, not for the initial 402 response.

Fix

Change the default to false to enable lazy initialization: the facilitator is contacted only when an actual payment needs to be verified, not on every cold start.

Users who need eager initialization (e.g. long-running servers) can still pass syncFacilitatorOnStart: true explicitly.

Changes

  • index.ts: changed default from true to false in all 3 exported functions (paymentMiddlewareFromHTTPServer, paymentMiddleware, paymentMiddlewareFromConfig) and updated JSDoc
  • index.test.ts: updated retry test to pass syncFacilitatorOnStart: true explicitly since it tests behavior specific to that mode

Testing

All 36 tests pass.

…ess compatibility

Fixes x402-foundation#2157

The previous default of true caused cold-start timeouts on serverless/edge
environments (Cloudflare Workers, AWS Lambda) because paymentMiddleware()
would block the first request while fetching facilitator support data.

The accepts/extensions data needed to emit a 402 is already known from
route config — facilitator init is only needed at verify/settle time.

Changing the default to false enables lazy initialization: the facilitator
is contacted only when an actual payment needs to be verified, not on
every cold start. Users who need eager initialization can still pass
syncFacilitatorOnStart: true explicitly.

Updated the retry test to pass syncFacilitatorOnStart: true explicitly
since it tests behavior specific to that mode.
@vercel
Copy link
Copy Markdown

vercel Bot commented May 7, 2026

@lau90eth is attempting to deploy a commit to the Coinbase Team on Vercel.

A member of the Team first needs to authorize it.

@phdargen
Copy link
Copy Markdown
Collaborator

phdargen commented May 7, 2026

Thanks for the contribution @lau90eth but this wont fix the issue, see #2157 (comment)

@phdargen phdargen closed this May 7, 2026
@lau90eth
Copy link
Copy Markdown
Author

lau90eth commented May 7, 2026

Reopened as #2221 with the proper fix as suggested — root cause was in buildPaymentRequirements() in @x402/core, not just the default change. Thanks for the detailed feedback.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

sdk Changes to core v2 packages typescript

Projects

None yet

Development

Successfully merging this pull request may close these issues.

@x402/hono: paymentMiddleware syncFacilitatorOnStart default makes discovery probes time out on cold serverless/edge isolates

2 participants