Form won't load
| Symptom | Likely cause |
|---|---|
| “Could not load form (404)” | No EMBED_FORM_<id> setting exists for that ID, or its value isn’t valid JSON. Check the setting name uses underscores where the link has hyphens. |
| “Could not load form (503)” | The entry’s server has no credentials in the HUBSTREAM_SERVERS setting, or no forms are registered at all. |
| “Could not load form (502)” | Hubstream rejected the request — usually the name isn’t the exact server-side name (management-UI forms are HubUI…-prefixed), or the API key is wrong. |
| Security check won’t load inside an iframe | The host page’s domain is missing from the Turnstile widget’s allowed hostnames in the Cloudflare dashboard. |
Submission fails
| Symptom | Likely cause |
|---|---|
| “No entityName configured” | The form’s viewform registry entry is missing entityName (the root entity). |
| A 400 error naming an upload field | The HFImages/HFPDFs field isn’t the JSON data type in Hubstream — see Image and PDF Uploads. |
| “Try again later” | The visitor hit a rate limit — see How Submissions Are Protected. |
| Submit says to reload the page | The page was open across a deployment or for 8+ hours; reloading fixes it. |
Configuration changes don't take effect
The Azure portal’s Environment variables page needs a double save: confirm the variable’s edit dialog and click Apply on the page. Until the second save, the old value stays live.
Prefill parameter is ignored
- The parameter name must match a field name or caption (case, spaces, and punctuation are ignored — but the letters must match).
- For dropdowns, the value must match an option’s label or ID; otherwise it’s skipped.
A test submission "succeeded" but no record appeared
The invisible bot trap gives fake successes to submissions it classifies as bots. If a browser extension auto-filled hidden fields (aggressive form fillers can), the submission was silently dropped. Retry in a private/incognito window with extensions off.
Attachments are missing from a new record
Files travel separately from the submission — Hubstream retrieves them from the file service after the record is created, so attachments can appear slightly later. If they never appear, check the upload field’s data type is JSON.