Cloudflare Turnstile: What Kept Breaking My Signup Form

A developer's investigation into a broken newsletter signup form found that Cloudflare Turnstile's readiness callback could spawn a second widget while a signup POST was pending, and an error from that widget could abort the in-flight request. The developer traced the failures to an invalid server secret, generated HTML that dropped the public sitekey, and an AI-assisted repair that used a readiness method the real Cloudflare API rejected, replacing the incompatible ready() call with deferred onload handling. All 21 widget error reports carrying phase evidence showed idle/not-started states, so the underlying challenge-failure cause remains unknown, and the fixes did not establish how many readers were lost.

Cloudflare Turnstile: What Kept Breaking My Signup Form My newsletter form could cancel its own signup request after Turnstile reported success. In a controlled reproduction, a repeated readiness callback created another widget while the POST was pending. An error from that widget could abort the request already in flight. That was one failure in a longer investigation of my blog's signup form. A server secret had been invalid. Generated HTML had lost the public key. An AI-assisted repair passed local tests but used a readiness method the real Cloudflare API rejected. Meanwhile, idle widget errors made the logs look like failed submissions. The code now makes ownership explicit: which attempt owns a callback, which durable record permits an email, and which observation establishes acceptance. A token, an HTTP response and an active subscription each prove different things. The changes below fixed reproducible defects and gave those stages separate evidence. They did not explain every challenge failure or establish how many readers I had lost. Find the last stage you can prove Turnstile's widget uses a public sitekey; server-side validation uses a private secret. Between the generated page and an active subscription, there are several opportunities for one part to work while the next part fails. For a similar integration, I would start with this diagnostic map. The final column distinguishes findings from the validation policy I implemented. | Symptom | Stage to inspect | Decisive check | Finding or policy here | |---|---|---|---| | invalid-input-secret | Server credential | Read the actual Siteverify result; test the deployed widget and secret together | Installing an existing recognized secret was followed by successful real verification | | Widget cannot initialize because its sitekey is missing | Generated browser configuration | Read the served form's dataset and render that form through the actual SSG | Direct attribute binding restored the key; a hand-built test DOM had hidden the defect | | Readiness exception with a deferred script | Native script integration | Exercise the real API with the actual script tag and initialization method | Deferred onload handling replaced the incompatible ready call | | 300031 in a widget error report | Challenge lifecycle | Read the attempt phase and operation state alongside the code | All 21 reports with phase evidence said idle/not-started; their challenge-failure cause remains unknown | | Token rejected after the browser obtains it | Server validation | Inspect the validation result and the application's hostname/action policy | Policy: distinguish expiry/reuse, service failure and hostname/action rejection | | Accepted response with no new email | Signup outcome | Join the request to its admission/send record, then check mailbox receipt and activation | Some accepted requests intentionally send nothing; one designated fresh cycle completed | An absent report is another uncertainty. Reporting can fail, and stored records have retention limits. This map depends on positive evidence at the relevant stage; it cannot reconstruct every earlier attempt. Make callbacks belong to one attempt The client already tracked verification and sending, but its readiness path could create a widget outside that lifecycle. A ready event was allowed to render while the form was already sending. Its error callback then entered the same failure handler used by verification and aborted the pending POST. The attempt model https://github.com/gkoreli/blog/blob/b94063aa/packages/blog/src/client/subscription-attempt.ts now owns one identity and a small lifecycle: verifying, sending, settled. Waiting for the API, rendering and interaction are steps inside verification. Its commands check both state and the deadline. Timer callbacks can arrive late in a background tab; checking the clock only in a timer would leave expired commands usable. The DOM and provider adapter own a separate widget generation. Retiring that generation happens before cleanup, so a callback fired during removal is already stale. The model contains no DOM, fetch, email address or provider object. | Event ordering reproduced locally | Rule enforced by the repair | |---|---| | Readiness repeats during a held POST | Sending cannot create a verification widget | | execute calls success synchronously, then throws | Token handoff has already transferred ownership to sending; the old stack cannot cancel it | | An old render returns after a replacement widget exists | Old cleanup cannot clear the replacement's slot | | Both native removal and the DOM fallback throw | Cleanup is reported separately and cannot prevent the single signup POST | | A token or expiry callback repeats after handoff | A retired widget cannot send again or settle the request | My recovery allowlist covers 300 / 600 error callbacks, iframe load error 200500 , and timeout codes 110600 / 110620 . It permits one fresh widget under the same attempt identity and existing deadline. Native retry is set to 'never' ; I own that recovery rather than combining two retry mechanisms. A repeated failure restores manual retry. Eligibility is a recovery policy, not a diagnosis of an internal suffix. Native browser controls checked the actual generated forms and client with Cloudflare's native script and official dummy keys https://developers.cloudflare.com/turnstile/troubleshooting/testing/ , which give fixed test behavior. Two concurrent forms each started one POST, survived repeated readiness while both responses were held, then completed when the local receiver released them. An always-failing dummy key produced one replacement, two reports under one attempt and no POST. Those controls exercise real script integration against a local receiver. They do not test a human checkbox, production hostname enforcement or email delivery. Browser reproductions and native receipts https://github.com/gkoreli/blog/blob/b94063aa/packages/blog/drafts/research/newsletter-reliability/33-browser-attempt-domain.md . The fake API accepted what the real API rejected The readiness regression was an example of a test missing the contract it needed to check. I asked the agent to read the authoritative documentation and native API capabilities. It added turnstile.ready . The fake implementation in its tests called the supplied callback immediately. The deployed browser failed, and inspection of the captured public API identified the async/defer guard and native error 3857 . Cloudflare's rendering documentation https://developers.cloudflare.com/turnstile/get-started/client-side-rendering/ includes a deferred-script example with an onload callback. Its advanced example using ready loads the script synchronously. We combined the loading mode from one example with the readiness method from another. The corrected integration installs a global callback before loading the provider script: <script window.gkTurnstileScriptState = 'loading'; window.gkTurnstileReady = = { window.gkTurnstileScriptState = 'ready'; window.dispatchEvent new Event 'gk-turnstile-ready' ; }; </script <script src="https://challenges.cloudflare.com/turnstile/v0/api.js?render=explicit&onload=gkTurnstileReady" defer </script This snippet signals readiness. The form initializer https://github.com/gkoreli/blog/blob/b94063aa/packages/blog/src/client/subscribe.ts listens for the event. It creates a widget only for an active attempt; if the API is already available, that attempt can start directly. A submission waiting for the script starts verification once. If loading never finishes, a deadline restores the form. Those states are necessary; the callback alone is not a complete initializer. The regression test now supplies a ready method that throws and checks that this deferred integration never calls it. Separate tests cover delayed and absent loading. That loader correction passed the November 5 UTC real browser signup recorded later in this article. Reading the right documentation and running mocks had both been useful, but neither had exercised the invalid combination we shipped. Test the runtime that will run the repair The deeper audit nearly introduced another integration failure. Provider requests followed redirects by default. A local control showed a 307 forwarding the synthetic Siteverify secret/token body to a second owned origin. The proposed fix, redirect: 'error' , passed Node tests. Workers rejected that option before sending any request. Its native Request contract https://developers.cloudflare.com/workers/runtime-apis/request/ supports follow and manual , and documents the unsupported error mode. A local workerd control reproduced the exception at my site's 2026-03-06 compatibility date. This proposal was corrected before delivery. The server adapters now use manual and explicitly reject redirects. Native controls check both sides: ordinary verification and email requests still work, while redirected requests make zero calls to the target. A test that only expected a redirected request to fail would have passed an adapter that broke every request. Browser Fetch supports the error mode; the signup client uses it there. Response reading needed its own boundary too. Getting headers does not finish a request. The server keeps each attempt's original five-second verification or eight-second email budget through bounded body consumption; headers do not start another full budget. Actual-byte limits and nonblocking cancellation cover unfinished or oversized streams. These are bounded application policies checked in the local runtime, not measured production latency guarantees. Preserve what you know across retries The browser's token handoff is also a side-effect boundary. Once the POST starts, losing its response cannot establish that the server did nothing. I do not automatically replay that POST. Responses that leave the signup outcome uncertain, including gateway failures, give check-inbox guidance before another attempt. Even HTTP 202 needs its application contract. The old client treated the status alone as accepted. It now requires JSON containing exactly { "ok": true } , read within the same thirty-five-second request budget and a 4 KiB body cap. A 202 HTML page or unfinished body stays unconfirmed. The request reference and observed status survive a failed body read, so diagnostics retain the last fact the browser actually received. The server has different retry rules. Turnstile tokens https://developers.cloudflare.com/turnstile/get-started/server-side-validation/ expire after five minutes and are single-use; Siteverify supports a UUID idempotency key when retrying validation. My verifier permits two bounded calls with the same UUID and identical body. Invalid-secret failures stop immediately. Successful validation requires the expected hostname and rejects another nonempty action. Missing or empty action remains an explicit cached-client exception. The provider decoder also checks the whole relevant verdict. A synthetic reply with success: true and error-codes: "invalid-input-response" previously crossed admission. It now returns verification unavailable. This is a contract test, not a claim that Cloudflare emitted that contradiction in production. Email retry needs a further distinction. The sender reused its body and idempotency key, but its last response could overwrite an earlier uncertain outcome. A controlled first call lost its response after possible acceptance; a second returned 400 . The old code called the operation failed. That second response could not establish what happened on the first call. | Evidence for the email operation | Knowledge retained | |---|---| | Non-retryable rejection on the first call, such as 400 | Failed; stop without another call | | Lost response or malformed acceptance receipt | Unknown; preserve the charged admission | | Unknown first result, then a rejection | Still unknown | | Valid accepted replay for the same operation | Accepted by the provider | | Accepted result, then lost database-write acknowledgment | Acceptance known; receipt persistence unconfirmed | Resend retains idempotency keys for twenty-four hours https://resend.com/docs/dashboard/emails/idempotency-keys . My sender retries during the same signup request, with at most two bounded calls using the same body and key. A second call is limited to transport loss/timeout, HTTP 5xx or 409 , an invalid success receipt, or a 429 with a supported numeric wait of at most three seconds one second when absent . A durable admission stays charged for accepted, failed and unknown outcomes. Provider contract reproductions https://github.com/gkoreli/blog/blob/b94063aa/packages/blog/drafts/research/newsletter-reliability/34-provider-contract-boundaries.md . Configuration can fail on either side of the browser The loader needed a public key in the browser and a valid private secret on the server. Both boundaries had failed at different times. In September, a legitimate signup failed with invalid-input-secret . My form suggested retrying or allowing bot protection in the browser. Those instructions could not repair the server credential. Cloudflare distinguishes secret errors from response-token errors https://developers.cloudflare.com/turnstile/get-started/server-side-validation/ ; the application needs to preserve that distinction when deciding what the reader can usefully do. The September 9 live test reproduced the failure. Installing an existing recognized secret in the Worker was followed by successful verification and a completed signup. A binding's presence had not established that its value worked. The dated acceptance https://github.com/gkoreli/blog/blob/ed00e62/packages/blog/drafts/research/newsletter-reliability/15-live-signup-acceptance.md does not identify who installed the earlier value or when it became invalid. In October, the build had a public key but the generated form had no data-turnstile-sitekey attribute. I use @nisli/core templates and static generation. This opening-tag fragment tried to insert optional attribute syntax through a nested template: novalidate${turnstileSiteKey ? html data-turnstile-sitekey="${turnstileSiteKey}" : ''} The nested template was not an attribute-syntax string. The installed renderer produced malformed attributes and lost the key. An isolated build reproduced the saved production HTML. The repair bound the value directly: novalidate data-turnstile-sitekey=${turnstileSiteKey} The old client tests had supplied the expected dataset by hand. They tested the client after bypassing the broken handoff. The replacement coverage renders the actual forms, reads their DOM attributes and initializes the actual client from a snapshot. The build also rejects a configured main form missing its key. Reproduction and repair https://github.com/gkoreli/blog/blob/ed00e62/packages/blog/drafts/research/newsletter-reliability/17-rendered-sitekey-regression.md . For a form fed by generated HTML, inspect the value where the client consumes it. The successful September verification did not prove that October's generated form still delivered its key. Interpret an error in the attempt that produced it The logs that prompted the latest investigation contained 49 retained client errors in a fixed window: October 6 at 00:00 through November 5 before 15:15 UTC. Of those, 48 were widget errors. Only 21 had phase/provider evidence; all 21 reported idle , operation not-started , and code 300031 . The other 27 widget reports lacked that evidence. Query, aggregate and limits https://github.com/gkoreli/blog/blob/ed00e62/packages/blog/drafts/research/newsletter-reliability/27-current-idle-widget-errors.md . My form rendered its widget at initialization and executed the challenge on submission. Rendering could still invoke an error callback before an attempt was active. The application logged it under subscribe form and displayed a verification-failed message. The component label and visible message made the event look like a failed signup. Cloudflare's error reference https://developers.cloudflare.com/turnstile/troubleshooting/client-side-errors/error-codes/ groups 300 as generic challenge failure and reserves the remaining digits for internal use. I found no public diagnosis of 031 there. The code does not independently identify the operators as bots, and the report count does not establish subscriber loss. The phase describes the callback being reported. An idle record cannot tell me whether that operator tried to subscribe earlier. Missing phase information leaves the older reports unresolved too. The first repair stopped showing a failed-subscription message for an idle callback. The later refactor goes further: an idle form creates no widget. Submission captures an intent, creates a random attempt reference and gives its widget a defined lifetime. That changes what the logs can count. Fewer idle widget errors after lazy initialization would follow from creating fewer idle widgets; it would not independently establish better signup completion. I need comparable builds and submitted-attempt outcomes before interpreting a rate change. Phase, timing and build context can segment the retained failure reports. They do not supply a count of all submitted or completed attempts. Keep widget mode separate from its timing I moved the existing widget from Invisible to Managed so verification could ask for interaction when needed. Cloudflare recommends Managed mode https://developers.cloudflare.com/turnstile/concepts/widget/ , which can choose a non-interactive check or a checkbox. This was a choice about the recovery path available to the reader. I did not establish that Invisible caused 300031 or measure a false-rejection improvement after switching. The client controls two other decisions: execution: 'execute', appearance: 'interaction-only', size: 'compact', Execution controls when the challenge runs; appearance controls when the widget becomes visible. These are separate settings https://developers.cloudflare.com/turnstile/get-started/client-side-rendering/widget-configurations/ . In my form, submission starts execution and the compact widget appears when interaction is needed. An application deadline also has to allow that interaction. My normal verification window is thirty seconds. The first before-interactive callback replaces it with a two-minute window; repeated callbacks cannot extend it indefinitely. These are application limits tested with controlled callbacks, not provider defaults. The accepted live cycle did not require a checkbox, so it does not validate every interactive browser condition. Put the business boundary in the code The server now separates confirmation policy from HTTP, SQL and provider responses. Its application coordinates verification, durable admission and a delivery receipt; each has an explicit outcome. Application boundary and checks https://github.com/gkoreli/blog/blob/b94063aa/packages/blog/drafts/research/newsletter-reliability/37-confirmation-application-boundary.md . The public signup and resend routes admit at most one confirmation per address per ten minutes, three per address per rolling day, and shared ceilings of 25 per rolling hour and 100 per rolling day. These are policy values, not measured safe thresholds. The shared budget remains inside one D1 transaction. Moving its check into an in-memory object would let concurrent Workers admit against separate counts. The transaction reserves before the external call; a subscriber-write failure rolls back admission. A fresh native D1 control admitted once from forty-eight concurrent admission calls for one address, alternating signup and resend modes. It exercises the store directly. That transaction cannot contain the email provider. There is no outbox or automatic crash replay. A Worker can stop after reserving and before sending, leaving an unused but charged admission. A send already admitted can finish after an opt-out. Those tradeoffs remain explicit. Closed logs preserve the last observed stage without email addresses, tokens or arbitrary provider text. Even an unexpected delivery-adapter exception records unknown; it cannot authorize another send. Prove the outcome after verification During the earlier live check, my own success message confused me: Request received. If confirmation is needed, check your inbox and spam folder. No email? You can try again in ten minutes. It was the normal HTTP 202 branch, styled in the same rust color as errors. The response intentionally kept subscription membership private: an already-active or suppressed address, or one inside its cooldown, could receive it without a new email. I kept that protection, separated pending/success/error styling and explained the existing-subscriber case. The accepted response now communicates its limited promise more clearly. It still cannot establish mailbox receipt or activation. During a later no-send check, an already-loaded page reached a newer Worker. Its retained trace showed successful real verification followed by unchanged and 202 . Before/after readback found the active state and confirmation ledger count unchanged. Joining the request to its receiving Worker mattered: the page's build ID named that page build, not the receiving server. Dated production check https://github.com/gkoreli/blog/blob/cca34028/packages/blog/drafts/research/newsletter-reliability/2026-11-06-browser-production-no-send.md . The diagnostic path needs evidence too. My default reporter now expects a 204 returned after confirmed storage. A bounded early reporter covers selected main-script, Turnstile-script and CSP failures, but cannot report when its own JavaScript or network request cannot run. Attempt references help join client evidence to server activity even without a received response; they remain client-supplied lookup hints. The reporting record https://github.com/gkoreli/blog/blob/ed00e62/packages/blog/drafts/research/newsletter-reliability/28-managed-verification-and-diagnostics.md keeps the details and controlled readbacks. Logging an error is not itself proof of storing it. On November 5 UTC, one designated signup cycle passed real verification, produced one accepted confirmation and reached Gmail Inbox with SPF, aligned DKIM and DMARC passing. I confirmed the message before the agent opened its link; the agent then independently read active state and a cleared confirmation hash. The Worker verification/send events matched the same durable admission. Stage-by-stage receipt https://github.com/gkoreli/blog/blob/ed00e62/packages/blog/drafts/research/newsletter-reliability/subscription-recovery-live-acceptance.json . Signed bounce and complaint handling was verified later with Resend's inert test addresses, separately from that signup cycle. The follow-up acceptance https://github.com/gkoreli/blog/blob/e089f77/packages/blog/drafts/research/newsletter-reliability/30-signed-resend-feedback-acceptance.md closes that setup gap without adding a claim about real-reader delivery. The new browser, provider and D1 controls above were a later engineering iteration. The completed Inbox cycle remains its own dated production result; it does not certify every subsequent revision. Native dummy-key success, source delivery, Worker activation and a completed subscription each need their own receipt. The blog still uses Turnstile. The repairs give each attempt a lifecycle and keep uncertain side effects uncertain. I can now test which boundary fails without using one generic widget error as the explanation for the whole signup. The cause of the 21 300031 reports with phase evidence remains unknown, and the rate at which legitimate readers finish under real browser and network conditions remains unmeasured. Glossary | Term / claim | Primary source | Date | |---|---|---| | Sitekey, secret and Managed/Invisible modes | Cloudflare widget documentation https://developers.cloudflare.com/turnstile/concepts/widget/ | Updated April 16, 2026; checked November 5 | | Deferred onload and synchronous ready examples | Cloudflare client rendering https://developers.cloudflare.com/turnstile/get-started/client-side-rendering/ | Updated June 17, 2026; checked November 5 | | Execution, appearance and interaction callbacks | Widget configurations https://developers.cloudflare.com/turnstile/get-started/client-side-rendering/widget-configurations/ | Updated June 28, 2026; checked November 5 | | Generic challenge failures and internal suffixes | Client error codes https://developers.cloudflare.com/turnstile/troubleshooting/client-side-errors/error-codes/ | Updated September 25, 2026; checked November 6 | | Native retry options and callback logging | Client error handling https://developers.cloudflare.com/turnstile/troubleshooting/client-side-errors/ | Updated May 5, 2026; checked November 5 | | Secret errors, token lifetime and validation idempotency | Siteverify https://developers.cloudflare.com/turnstile/get-started/server-side-validation/ | Updated October 22, 2026; checked November 5 | | Workers redirect capability | Workers Request API https://developers.cloudflare.com/workers/runtime-apis/request/ | Checked November 5 Pacific / November 6 UTC; local compatibility date 2026-03-06 | | Email retry identity and retention | Resend idempotency keys https://resend.com/docs/dashboard/emails/idempotency-keys | Checked November 5 Pacific / November 6 UTC | | Sequential transactional admission | D1 batch https://developers.cloudflare.com/d1/worker-api/d1-database/ | Checked November 5 Pacific / November 6 UTC | The wider audit also repaired webhook authentication of decoded rather than original bytes https://github.com/gkoreli/blog/blob/b94063aa/packages/blog/drafts/research/newsletter-reliability/36-request-body-and-webhook-contracts.md and campaign sends without durable admission https://github.com/gkoreli/blog/blob/b94063aa/packages/blog/drafts/research/newsletter-reliability/35-campaign-admission.md ; those adjacent defects do not explain Turnstile's generic challenge errors. The prompt record https://gkoreli.com/cloudflare-turnstile-signup-failures/prompts preserves eight selected shaping messages in full. An operational authorization containing a private email and unrelated housekeeping are omitted.