Microphone Permission Denied or AudioRecorderFailure

On Headless Web SDK, microphone start failures come back as StartSessionFailed or ResumeSessionFailed with reason AudioRecorderFailure. That covers failed mic access or start, including when an exact deviceId is unavailable. It is not a top-level error code on its own. On Mobile SDK, related cases are needMicrophonePermissionRecording, micIsInUse, appIsNotActive, and unableToStartRecording.

Common causes

The browser blocked microphone permission for your origin.
You passed an exact deviceId that is missing or disconnected. Headless Web SDK does not fall back to the browser default in that case.
Microphone access needs HTTPS in production (Headless Web SDK prerequisites).
On Mobile SDK, mic permission was not granted, another app holds the mic, or the app is in the background.

Fix (Headless Web SDK)

Confirm Permission and HTTPS

Prompt for microphone permission and confirm the site is allowed. In production, request microphone access over HTTPS. If your app is embedded in an iframe, add allow="microphone; clipboard-write" on that iframe.

Inspect StartSessionFailed or ResumeSessionFailed

On Platform Client, check code: "StartSessionFailed" or code: "ResumeSessionFailed" with reason: "AudioRecorderFailure", plus cause for the underlying getUserMedia error. In React useAmbientSession, start or resume often rethrows a string from error.toString() that includes those Code and Reason values.

Refresh deviceId and Retry

If you pass config.audio.deviceId (or { audio: { deviceId } } on Platform Client), refresh your device list, ask the user to pick another mic, then retry. Optional deviceId needs Headless Web SDK v0.3.1 or later. Omitting deviceId uses the browser default microphone.

Pause Before Switching Mics

Changing deviceId while recording does not switch the mic already in use. Call pause(), then resume(), after you update the device. There is no public switchMicrophone API.

// Permission unlocks readable device labels in Chromium.
const permissionStream = await navigator.mediaDevices.getUserMedia({
  audio: true,
  video: false,
});
permissionStream.getTracks().forEach((track) => track.stop());

const devices = await navigator.mediaDevices.enumerateDevices();
const inputs = devices.filter((device) => device.kind === "audioinput");

When deviceId is set, capture uses getUserMedia with that exact device. Your app owns device enumeration and picker UI. The Headless Web SDK does not list microphones for you.

Fix (Mobile SDK)

Error id	What it means	What to do
`needMicrophonePermissionRecording`	Microphone permission has not been granted	Request mic permission, then retry start or resume
`micIsInUse`	Another app is using the microphone	Free the mic in the other app, then retry
`appIsNotActive`	Recording cannot start while the app is in the background	Bring the app to the foreground before recording
`unableToStartRecording`	Audio engine setup failed	Check inputs and `AVAudioSession` (or platform equivalent)

Next steps

micIsInUse on Mobile SDK - Free the device microphone AppIsNotActive on Mobile SDK - Recording while backgrounded Manage ambient session - deviceId, start, pause, and resume Audio capture best practices - Capture format before Partner WebSocket streaming sessionAlreadyExists - Remote ambient session conflicts on create

​Common causes

​Fix (Headless Web SDK)

​Fix (Mobile SDK)

​Next steps

Common causes

Fix (Headless Web SDK)

Fix (Mobile SDK)

Next steps