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

# Dictation SDK Error Handling

> Learn to fix common Dictation SDK issues: auth, CSP, layout, missing callbacks, and client-only runtime requirements

The Dictation SDK does not return one consistent error code for every problem. Instead, several systems have to work together: the **Suki platform** handles **authentication**, the hosted UI runs inside an **iframe**, and your app passes **`rootElement`** and **callbacks**. When one piece is wrong, you often only see a vague symptom, such as **no UI**, **dictation closing immediately**, or **broken layout**.

Work through this page in this order: **runtime** (browser and timing), **layout** (**`rootElement`** and CSS), **auth and CSP**, then **configuration and callbacks**. That order usually finds the cause fastest.

For every field on **`AuthConfig`** and **`ShowOptions`**, use [Configuration](/dictation-sdk/guides/configuration).

<Tip>
  The **wrapper** pattern for **`rootElement`** (stable height, **`position: relative`**) is documented on [Configuration guide wrapper layout](/dictation-sdk/guides/configuration#wrapper-layout).
  Refer to that page if you are not sure how to structure your DOM.
</Tip>

## Runtime requirements

The Dictation SDK is built for **in-browser** embedding. It is **not** a Node-only or server-rendered iframe product.

<CardGroup columns={2}>
  <Card title="Supported environments" icon="check">
    Browser environments where you can create an `HTMLIFrameElement`, use `postMessage`, and measure a DOM container
  </Card>

  <Card title="Not supported" icon="x">
    Using Node.js as the environment that hosts `DictationClient` or the dictation iframe
    Relying on **SSR** alone to render dictation; initialize and call `show()` on the client after the document (and your `rootElement`) exist
  </Card>
</CardGroup>

<Card title="The SDK expects" icon="cube">
  * A real `HTMLIFrameElement` (the SDK creates and manages it inside your container)
  * `postMessage` between your page and the hosted UI
  * Layout information so the iframe can size to `rootElement`
</Card>

<Note>
  Dictation runs in the **browser** only. The iframe is not created during **SSR** or on the server.

  Call **`show()`** only after **`rootElement`** points at an element that **already exists** in the DOM and has been laid out (so it has a real size). If you call too early, **`rootElement`** may be **`null`** or zero height.

  * [React integration](/dictation-sdk/react-integration/react) for **`DictationProvider`** and **`Dictation`**
  * [Configuration examples](/dictation-sdk/guides/examples/configuration-examples) for sample **`rootElement`** wiring
</Note>

## Layout and root element related issues

The iframe **fills the layout box** of the element you pass as **`rootElement`**. Common mistakes are as follows:

* A **zero-height** parent
* A flex or grid child that **shrinks to zero**
* **`overflow: hidden`** on a parent that clips the overlay

### Recommended approach

* Use a dedicated **wrapper** around the dictation region, not the raw **`<textarea>`** as **`rootElement`**, unless you are sure that node has a stable box.
* Give the wrapper a **defined height** or **`min-height`**, and usually **`position: relative`**.

<Expandable title="Recommended wrapper CSS" defaultOpen="true">
  ```css CSS theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  .wrapper {
    position: relative;
    height: 100%;
  }
  ```
</Expandable>

For a longer explanation, refer to [Wrapper layout section](/dictation-sdk/guides/configuration#wrapper-layout) on the Configuration guide.

<Tip>
  If **`rootElement`** is **`null`** (wrong id, node not mounted yet, or **`show()`** before layout), **`show()`** can fail or show a blank area.
  Resolve the DOM first, then retry. Use the [try / catch section](/dictation-sdk/guides/error-handling#wrap-show-in-try-/-catch) below to log or surface that error.
</Tip>

## Authentication and CSP related issues

<Expandable title="Error sources" defaultOpen="true">
  <ResponseField name="SukiAuthManager" type="Auth">
    **Invalid** **`partnerId`**, **`partnerToken`**, or wrong **`environment`** can block sign-in. The iframe will not initialize until auth succeeds. Start with [Authentication](/dictation-sdk/guides/authentication) and confirm credentials with your Suki contact.
  </ResponseField>

  <ResponseField name="Iframe / CSP" type="Iframe">
    The hosted dictation UI loads in an iframe. If your **CSP** blocks that frame source, or the host URL is not allowlisted for your program, the UI will not appear or will fail silently in the network panel. Check frame ancestors, **`frame-src`** / **`child-src`**, and any partner-specific allowlist docs you were given.
  </ResponseField>
</Expandable>

## Configuration related issues

<Expandable title="Error sources" defaultOpen="true">
  <ResponseField name="Configuration" type="Config">
    A missing **`onSubmit`** callback often makes dictation **close immediately** after the user acts. Other required fields (**`mode`**, **`fieldId`**) must also be set; refer to [Configuration](/dictation-sdk/guides/configuration) guide for more details.
  </ResponseField>
</Expandable>

### Wrap show() in try / catch

`DictationClient.show()` can **throw** or reject when configuration or auth fails before the session is usable. Wrapping the call helps you **log** and **surface** errors in your own UI.

```javascript JavaScript expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
try {
  await client.show({
    mode: "in-field",
    fieldId: "notes",
    rootElement: document.getElementById("dictation-root"),
    onSubmit: ({ text }) => applyText(text),
  });
} catch (err) {
  console.error(err);
}
```

## Troubleshooting

Below are some other common issues and how to troubleshoot them.

<Accordion title="Dictation UI not visible">
  Check, in roughly this order:

  * **Container height** and **`position`** on **`rootElement`** and parents ([Wrapper layout](/dictation-sdk/guides/configuration#wrapper-layout))
  * **Browser devtools** for blocked iframe requests or CSP violations
  * That **`rootElement`** is **not** **`null`** and matches the node you intend
  * **Authentication**: failed login or bad tokens (refer to [Authentication](/dictation-sdk/guides/authentication) guide)
</Accordion>

<Accordion title="Dictation closes immediately">
  This usually means **`onSubmit`** is **missing** or not wired correctly. The hosted UI expects a handler when the user commits. Refer to [Callbacks](/dictation-sdk/guides/callbacks) and [Configuration](/dictation-sdk/guides/configuration) guides for more details.
</Accordion>

<Accordion title="Multiple overlays or duplicate sessions">
  Create **one** **`DictationClient`** (with one **`SukiAuthManager`**) per **page scope**, and drive which field is active with your own state (for example a single **`activeFieldId`**). Multiple clients can each try to mount dictation. Refer to [JavaScript integration](/dictation-sdk/javaScript-integration/javaScript) and [React integration](/dictation-sdk/react-integration/react) guides for more details.
</Accordion>