Fix install, login, submit, mail, and webhook failures

These codes surface when the app refuses to run until configuration is repaired.

Submission redirects to not-sent with a wckd= query parameter

Intake rejected the POST after the public submit route forwarded the payload.

1. Copy the exact wckd token from the URL and compare it with the error-code notes below.
2. Confirm /form-submit routes to the correct WCKD Forms install or Lite install, per Routing & URLs.
3. Confirm the Lite installer uses the current ingest key shown in the main dashboard.
4. Retry slowly from a real browser session: wait on the page, move the mouse to satisfy human-interaction checks, then submit.

Common Lite-specific codes include NO_SCHEMA (missing local Lite schema), VALIDATION_FAILED (Lite schema does not match the dashboard schema), NO_INGEST_KEY, INGEST_UNAUTHORIZED, SATELLITE_INTAKE_DISABLED, and INTAKE_CURL_MISSING. See WCKD Forms Lite for setup details.

Thank-you redirect works but no row appears in Inbox

Different hosts or databases than you expect, or filters hide the row.

1. Confirm you are signed into the same environment (host + database) that received the POST.
2. Clear inbox filters and widen the date range.
3. Query the submissions table directly with read-only SQL to confirm whether insert ran.

Staff notification never arrives

SMTP misconfiguration or empty routing addresses; intake may still insert the row.

1. Open Settings → Operations and verify SMTP host and username are either both filled or both empty.
2. Open Settings → Forms for the template you tested and confirm routing toggles and “to” addresses.
3. Read PHP error logs after a reproducing submit; mail failures are logged while the submission remains.

Webhook endpoint never logs a POST

The outbound job never passed validation or the master switch is off.

1. Confirm Enable outbound webhooks is checked under Settings → Operations → Outbound webhooks.
2. Confirm the row has When a submission is received checked for new rows, or at least one label under When status changes to for status edits, matching your test.
3. Confirm the URL begins with https:// and is not localhost or a private IP.
4. Search logs for [wckd-forms webhook] lines after reproduction.

Public page shows “unknown form schema” or similar

The registry key does not resolve to a readable schema definition.

1. Confirm the first argument to wckd_form() matches a form key exactly.
2. Confirm the matching form schema exists for that key.
3. On Lite sites, confirm the key exists in the Lite form map and the matching schema definition was copied.
4. Deploy PHP changes to the server you are testing, then hard-refresh the browser.

Browser shows a blank page when visiting the embed helper directly

Expected: the helper defines functions only and is loaded by normal pages.

1. Load a normal site page that calls wckd_form() instead (see Embed forms).

Primary Owner tools call the configured update service, then optionally download and apply a ZIP. Codes shown in the dashboard often start with WF-4xx.

1. Confirm the update-check URL in the generated app config points at the HTTPS shop host.
2. Run Check for updates before Install update now; resolve WF-401–WF-405 (URL, version, lock) first.
3. WF-410 / WF-411: download or checksum failure — verify the ZIP on the vendor server and package_download_sha256.
4. WF-412: the downloaded file is not a valid ZIP archive.
5. WF-413: ZIP layout — the archive does not match the expected package layout.
6. WF-414: PHP could not write into the live package; fix filesystem permissions or use the manual upgrade steps.
7. WF-415: database migration step failed after files were applied.
8. WF-416 / WF-417: enable PHP cURL and the Zip extension on the server.
9. WF-418: the installed version file could not be updated; check write permissions on the package tree.