Skip to main content

​
Overview

The Dictation SDK does not return one consistent error code for every problem. Instead, several systems have to work together: SDP 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.
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.
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
  • 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.
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.

​
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.
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)
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.
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.
Last modified on April 20, 2026