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 always return a single error code for every failure. A successful integration depends on several components working together, including authentication, the hosted iframe, the rootElement you provide, and your application callbacks. When one of these components is misconfigured, you may see symptoms such as the UI not rendering, the dictation window closing immediately, or layout issues instead of a specific error.

To troubleshoot efficiently, work through this guide in the following order:

1. Runtime (browser compatibility and initialization timing).
2. Layout (rootElement and CSS).
3. Authentication and Content Security Policy (CSP).
4. Configuration and callbacks.

This sequence helps isolate the most common integration issues first.

For detailed information about every AuthConfig and ShowOptions property, see Configuration.

The wrapper pattern for rootElement (stable height, position: relative) is documented on Configuration guide wrapper layout. Refer to that page if you are not sure how to structure your DOM.

Runtime requirements

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

Supported Environments

Browser environments where you can create an HTMLIFrameElement, use postMessage, and measure a DOM container

Not Supported

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

The SDK Expects

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

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 for DictationProvider and Dictation.
• Configuration examples for sample rootElement wiring.

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.

Hide Recommended wrapper CSS

CSS

.wrapper {
  position: relative;
  height: 100%;
}

For a longer explanation, refer to Wrapper layout section on the Configuration guide.

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 below to log or surface that error.

Authentication and CSP related issues

Hide Error sources

SukiAuthManager · Auth

Invalid partnerId, partnerToken, or wrong environment can block sign-in. The iframe will not initialize until auth succeeds. Start with Authentication and confirm credentials with your Suki contact.

Iframe / CSP · 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.

Configuration related issues

Hide Error sources

Configuration · 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 guide for more details.

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

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.

Dictation UI Not Visible

Check, in roughly this order:

• Container height and position on rootElement and parents (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 guide).

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 and Configuration guides for more details.

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 and React integration guides for more details.