Record SDK errors and troubleshooting

Every failure in the Record SDK carries a short, stable code. This page lists where errors arrive, what each code means and how to fix the problems developers run into most often.

Always branch on code, never on message. Messages are meant for logs and may be reworded.

Methods on DadanRecorder reject with a DadanSdkError:

import { DadanSdkError } from "@dadan-io/record-sdk";

try {
  await recorder.retryUpload();
} catch (error) {
  if (error instanceof DadanSdkError) {
    console.error(error.code, error.status, error.recoverable);
    if (error.recoverable) showRetryButton();
  }
}

already_recording, already_starting, upload_in_progress, stop_in_progress, not_recording, not_paused, cannot_switch_device_while_recording, no_blob_to_upload, videoId_required, not_initialized and destroyed mean a method was called in a state that does not allow it. Check getState() and the order of your calls.

Download helpers use their own codes, such as ORIGIN_DENIED and VIDEO_STILL_PROCESSING. They are listed in Embed and download recordings.

media.warning reports a problem that does not stop the recording:

• reason: "unavailable": the microphone could not be used in screen or both mode. Recording continues without it.
• reason: "ended": the microphone or camera stopped during recording, for example because it was unplugged.

The built-in studio shows its own notice for both cases. In a custom interface, tell the person so they are not surprised by a silent video.

The studio shows “Couldn’t start recording. Check that this page Origin is allowlisted for your Dadan public app, then try again.” and you receive auth_failed with the message session_failed (403 ORIGIN_DENIED).

The origin in the address bar must exactly match one of the origins allowlisted for your public app ID:

• The scheme counts: http:// and https:// are different.
• The host counts: example.com, www.example.com and 127.0.0.1 versus localhost are all different.
• The port counts: http://localhost:5173 and http://localhost:3000 are different.

In the browser console, a refused session can also appear as a CORS error or as “Failed to fetch”. The fix is the same. To add an origin, open Account & Settings, then Developers, and edit your app in the Public Apps section. See Get a public app ID.

1. Check that the page is served over HTTPS or from localhost. Browsers block capture on other http:// pages, and isSupported() returns false.
2. Open the browser console and look for errors from the SDK.
3. Make sure the studio was created before the click. With your own button, keep it disabled until the SDK is ready, as the framework guides show.

That is expected. Mobile browsers do not support screen capture, so only camera and audio are available there.

macOS must allow the browser to record the screen. Open System Settings, go to Privacy & Security, then Screen & System Audio Recording (called Screen Recording on older versions), enable your browser and restart it.

System and tab audio depend on the browser and the operating system. In Chrome and Edge, audio is most reliable when the person shares a tab and turns on the option to share its audio in the browser’s picker. Microphone audio is not affected.

The take stays in the browser, so nothing is lost straight away. Offer a retry: in the built-in studio, the person can click Retry upload; with DadanRecorder, call retryUpload(). If the page is reloaded, the studio offers to restore the take for up to 24 hours.

New uploads need a short processing time. Use fetchVideoDownloadWithRetry or recorder.fetchDownload(), which retry automatically.

Your tsconfig.json uses the legacy "moduleResolution": "node". Switch to "bundler", "node16" or "nodenext", which understand package subpath exports.

Vue and plain JavaScript projects may see one warning about a "use client" directive from the studio package. It is harmless and can be ignored.

The studio injects a <style> element. Pass your CSP nonce (styleNonce, or the nonce attribute on <dadan-recorder>). See the production checklist.

Contact Dadan support from this Help Center. Include the error code, the message, the page origin, your browser and operating system, and your public app ID. Do not send upload tokens or your API key.