Form Filling Session Returns No Results

A Form filling session can finish without the structured values you expected. Cancel and early close are normal session events. SUKI_FF_001 through SUKI_FF_004 are validation or runtime errors. Partial output shows up in FormFillingResult. Check the callback or error code before you change templates or auth.

Cancel vs closed vs empty structured data

These outcomes do not always emit SukiFormFillingError. Check the event or the FormFillingResult fields.

Situation	What happens	What you receive
Clinician cancels during selection or recording	Normal cancel	`onCancel` and `form-filling:cancelled`; no structured data
Clinician closes the processing screen early	Processing may still finish on the server	`form-filling:closed`; no `onSubmit` from that action
Late results after the foreground session changed	Results for a superseded session	`form-filling:background-submitted` / React `onBackgroundSubmit`
Some forms produce output, others do not	Partial success	`onSubmit` with values in `structured_data.non_generated_values` for empty templates
Processing takes longer than 60 seconds (online)	Timeout phase in the hosted UI	If the clinician leaves that screen open, results still arrive as `onSubmit` / `form-filling:submitted` for the same session

`FormFillingResult` field	Use it for
`structured_data.generated_values`	Forms with filled values; map `data` using `form_template_id` and `type`
`structured_data.non_generated_values`	Templates with no output in this session (often only `form_template_id`); skip or show empty state
`ambient_session_id`	Deduplicate saves (Form filling session ID, not an ambient clinical note session ID)
`correlation_id`	Match your encounter if you passed `correlation_id` at start

Do not rely on onSubmit alone to save results. If the clinician closes the processing screen or tab before results reach the browser, register a partner webhook so structured data still reaches your server.

Error codes that block or fail the session

Handle code and reason on SukiFormFillingError, not message text alone.

Code	Reason	When it happens	What to do
`SUKI_FF_001`	`empty-template-ids`	No forms after resolve	Pass at least one static or dynamic entry in `forms`
`SUKI_FF_001`	`unsupported-template-ids`	All static IDs unknown and no valid dynamic entries remain	Confirm enabled `template_id` values with Suki support, or add a valid `schema` entry
`SUKI_FF_001`	`invalid-form-entry`	XOR violated or non-JSON-serializable React props	Use exactly one of `form_template_id` or `schema` per entry
`SUKI_FF_001`	`duplicate-form-id`	Duplicate static or dynamic IDs	Make static IDs unique among themselves and dynamic `id` values unique among themselves
`SUKI_FF_002`	`handshake-timeout`	Iframe did not complete `ready` → `init-ack` within 10 seconds	Check network, HTTPS, and CSP `frame-src`
`SUKI_FF_003`	`fetch-templates-failed`	Template catalogue request failed during validation	Retry; confirm auth and staging vs production
`SUKI_FF_004`	`iframe-runtime`	Runtime error in the Form filling interface	Show retry; check microphone permission, network, and schema field rules

Template IDs differ for staging and production. Unsupported static IDs are dropped before the UI opens. Prefer forms; when forms is provided, form_template_ids is ignored.

Fix

Identify Cancel, Closed, or Submit

If you saw onCancel / form-filling:cancelled, there is no structured data to retrieve. If you saw form-filling:closed, wait for the partner webhook or handle form-filling:background-submitted if the clinician started another session.

Inspect FormFillingResult on Submit

On onSubmit or form-filling:submitted, map structured_data.generated_values. Treat structured_data.non_generated_values as forms with no output for this session, not as a silent SDK failure.

Handle SDK Error Codes

Listen on onError, form-filling:error, or React error from useFormFilling(). Fix SUKI_FF_001 forms configuration, SUKI_FF_002 CSP/network/HTTPS, SUKI_FF_003 auth/environment, or SUKI_FF_004 runtime issues using the table above.

Use a partner webhook for server-side delivery when the tab closes early. See Form filling SDK prerequisites and Signature verification.

Next steps

Form filling SDK error handling - Error codes and normal session outcomes Form filling SDK callbacks - FormFillingResult and webhook vs onSubmit CSP blocks the SDK iframe - Fix SUKI_FF_002 handshake timeouts Webhook deliveries are not arriving - Verify HMAC and return 2xx Form filling React integration - Early close and onBackgroundSubmit

​Cancel vs closed vs empty structured data

​Error codes that block or fail the session

​Fix

​Next steps

Cancel vs closed vs empty structured data

Error codes that block or fail the session

Fix

Next steps