Troubleshooting Forms and Submissions

Overview

Most StretchForms issues fall into a handful of buckets: a form won't save, responses aren't appearing, routing didn't do what you expected, a webhook is failing, or an advanced feature looks unavailable. Work through the sections below in order.

Forms won't save or update

"A form title is required." The name must be at least two characters. Enter a real title and save.

"A valid form key is required." Keys must be at least two characters and contain only lowercase letters, numbers, hyphens, or underscores. Remove spaces, capitals, and symbols — for example use client-intake, not Client Intake!.

The update was rejected as empty. An update must change at least one attribute. Adjust a field, status, or setting and save again.

I can't create, edit, or delete a form at all. Form writes require a step-up action token; an everyday read token isn't sufficient. If you're consistently blocked, you may not have write access — check with your administrator.

Responses aren't appearing

1. Is the form Active? Draft, Paused, and Archived forms don't accept new responses. Set the status to Active.
2. Do the form types match? Submissions are linked to a form by form type. If a response was created under a different type than the form uses, it won't associate. Align the types.
3. Are inbox filters hiding it? The Intelligence inbox filters by brand, form type, status, and pipeline stage. Clear the filters and look again.
4. Is it a contact/quote form? Those responses route to Messaging › Submissions — check there too.

Routing didn't work as expected

A contact form didn't route to Messaging. Automatic messaging routing triggers on contact/quote intent in the type, key, or title. Rename the form type to include contact or quote, or set the target app to Messaging manually.

Responses have no owner. Set a default team on the form so responses always have an owner, and confirm the routing mode matches your intent (Manual review keeps everything in the inbox for a person to assign).

The engine recommends a route but nothing moves. That's expected in Dry-run mode — recommendations are applied by a person. Switch to Team route or App handoff to automate.

Webhooks are failing

1. Check the delivery log for the last status code and error.
2. Non-2xx response: your endpoint must return a 2xx or the delivery retries (up to max attempts) and then fails.
3. Timeouts: each attempt times out at 8 seconds. Return quickly and do heavy work asynchronously.
4. Signature mismatch on your side: sign over "<t>.<rawBody>" using the exact timestamp from the x-stretchforms-signature header and the raw body, with the same signing secret.
5. Nothing arrives: confirm the endpoint is enabled, the URL is publicly reachable, and the form is Active. Use Test webhook to isolate the endpoint from the form.
6. Watch the needs-attention count on the dashboard — it surfaces queued, retrying, and failed deliveries.

Advanced features look unavailable

"StretchForms engine is not enabled." The Intelligence classification engine (spam/PII/routing/validation signals) is gated per workspace. When it's off, you still get the full inbox and triage tools — just without computed signals. Ask your administrator to enable the engine.

The AI form generator is missing. AI generation is flag-gated and depends on the AI service being ready. If you don't see it, ask your administrator to enable the forms AI capability. It always fails safe, so manual building is never blocked.

Partial saves and multi-step issues

Progress isn't saved. A partial save requires both a valid form key and a resume token. Confirm partial saves are enabled on the form.

A resume link doesn't restore answers. The partial save may have expired or already been submitted. The respondent will need to start again.

Analytics look wrong

Views are zero but submissions exist. View events are recorded when a form renders through StretchForms; a submission created via another path may lack view events. Rely on submission and completion metrics there.

Numbers are low right after launch. Analytics is cumulative — give a new form time and traffic before drawing conclusions.

When to contact support

If you've confirmed the form is Active, types match, filters are clear, and a webhook test still fails or the engine/AI won't enable for an admin, reach out to support with the form key, the approximate time of the issue, and — for webhooks — the delivery status code and error from the log. That's enough to trace it quickly.

Tips

• Reproduce as a respondent. Submitting a test response yourself surfaces most issues immediately.
• Change one variable at a time so you know which fix worked.
• Keep form keys and types consistent — most "missing response" mysteries are a type mismatch.