> ## Documentation Index
> Fetch the complete documentation index at: https://developer.suki.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Form Filling Session Returns No Results

> Tell cancel, early close, empty structured data, and Form filling SDK errors apart

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 |

<Warning>
  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](/documentation/webhook/overview) so structured data still reaches your server.
</Warning>

## 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 |

<Note>
  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.
</Note>

## Fix

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Register a Production Webhook">
    Use a partner webhook for server-side delivery when the tab closes early. See [Form filling SDK prerequisites](/form-filling-sdk/prerequisites#partner-webhook) and [Signature verification](/documentation/webhook/signature-verification).
  </Step>
</Steps>

## Next steps

<Icon icon="file-lines" iconType="solid" /> **[Form filling SDK error handling](/form-filling-sdk/guides/error-handling)** - Error codes and normal session outcomes

<Icon icon="file-lines" iconType="solid" /> **[Form filling SDK callbacks](/form-filling-sdk/guides/callbacks)** - `FormFillingResult` and webhook vs `onSubmit`

<Icon icon="file-lines" iconType="solid" /> **[CSP blocks the SDK iframe](/documentation/troubleshooting/csp-blocks-sdk-iframe)** - Fix `SUKI_FF_002` handshake timeouts

<Icon icon="file-lines" iconType="solid" /> **[Webhook deliveries are not arriving](/documentation/troubleshooting/webhook-deliveries-not-arriving)** - Verify HMAC and return 2xx

<Icon icon="file-lines" iconType="solid" /> **[Form filling React integration](/form-filling-sdk/react-integration/react)** - Early close and `onBackgroundSubmit`