Fix Azure AI Immersive Reader Not Working

Start at the source: confirm that the Azure AI Immersive Reader resource itself is healthy and configured correctly. I've seen cases where developers use an existing general-purpose Azure AI Services multi-service resource and wonder why the Immersive Reader SDK keeps returning a 401. For the Immersive Reader, you need either a dedicated Immersive Reader resource or a properly configured multi-service resource, but the authentication flow and endpoint format differ between them.

In the Azure Portal, navigate to All Resources and find your Immersive Reader resource. Check these four things:

1. Resource type: It should show as Immersive Reader under the Kind column. If it says something generic, you may have the wrong resource type.
2. Status: The Overview blade should show Running. If it shows Disabled or has a warning banner, your subscription may have a spending limit or policy block in place.
3. Endpoint URL: Copy the endpoint from the Keys and Endpoint blade. This is the subdomain-based URL you pass as the subdomain parameter in your SDK call. A very common mistake is passing the full URL (including https:// and trailing slashes) when the SDK expects only the subdomain portion.
4. Region: Note which Azure region your resource is in. Your token acquisition request must target the correct regional endpoint. If your resource is in East US but your app is requesting tokens from the West Europe endpoint, authentication will fail.

To confirm your endpoint subdomain via PowerShell:

az cognitiveservices account show \
  --name "YourImmersiveReaderResourceName" \
  --resource-group "YourResourceGroup" \
  --query "properties.endpoint" \
  --output tsv

The output will be something like https://yoursubdomain.cognitiveservices.azure.com/, you only want the yoursubdomain part for the SDK's subdomain parameter.

If everything looks correct here, you should see a clean resource status page with no alerts. If there's a billing or quota issue, you'll see a red banner at the top of the Overview blade, resolve that before going further.

Azure AI Immersive Reader authentication runs through Microsoft Entra ID (formerly Azure Active Directory), and this is where the majority of Azure AI Immersive Reader authentication failures originate. The SDK does not accept raw subscription keys the way some other Azure AI services do, it specifically requires a bearer token obtained via Microsoft Entra. If your token acquisition is broken, the reader will not launch, period.

Open the Azure Portal and go to Microsoft Entra ID → App registrations. Find the app registration your application uses. Check the following:

Client Secret or Certificate: Under Certificates & secrets, verify your client secret hasn't expired. Expired secrets are a surprisingly common cause of sudden Immersive Reader failures that weren't happening before, the service worked fine and then just stopped one day. If the secret is expired, create a new one under the + New client secret button, then update your application's configuration with the new value.

API Permissions: Navigate to API permissions. You should see user_impersonation for Azure Cognitive Services listed. If it's not there or shows "Not granted", click + Add a permission → APIs my organization uses → search for "Cognitive Services" → select Delegated permissions → user_impersonation. Then click Grant admin consent.

To test token acquisition in isolation, run this PowerShell command with your actual values:

$tenantId = "your-tenant-id"
$clientId = "your-client-id"
$clientSecret = "your-client-secret"

$body = @{
    grant_type    = "client_credentials"
    client_id     = $clientId
    client_secret = $clientSecret
    scope         = "https://cognitiveservices.azure.com/.default"
}

$response = Invoke-RestMethod `
  -Method Post `
  -Uri "https://login.microsoftonline.com/$tenantId/oauth2/v2.0/token" `
  -Body $body

$response.access_token

If this returns an access token, your Microsoft Entra configuration is correct. If you get an AADSTS70011 or AADSTS50058 error code, your app registration or permissions need attention. An AADSTS700016 error means the application was not found in the directory, double-check you're using the right tenant ID.

Once authentication is solid, the next most common source of Azure AI Immersive Reader not loading is a malformed SDK call. The Immersive Reader JavaScript SDK is strict about how you structure the content object you pass to it, and it fails silently in ways that don't give you obvious error messages in the UI.

The SDK is available as an npm package (@microsoft/immersive-reader-sdk) or via CDN. Regardless of which you're using, the launchAsync call follows this structure:

import { launchAsync } from "@microsoft/immersive-reader-sdk";

const content = {
  title: "Your Content Title",
  chunks: [
    {
      content: "The text you want the reader to process.",
      lang: "en",
      mimeType: "text/plain"
    }
  ]
};

const options = {
  uiLang: "en"
};

try {
  await launchAsync(token, subdomain, content, options);
} catch (error) {
  console.error("Immersive Reader launch failed:", error);
}

The three most common mistakes I see here:

1. Missing lang in the chunk: The lang field inside each chunk is not technically required but its absence causes unpredictable behavior, especially with text-to-speech features failing to initialize. Always set it explicitly using the correct BCP-47 language tag (e.g., "en", "fr", "hi-IN").
2. Passing the full endpoint URL as subdomain: The subdomain parameter should be only the subdomain portion of your resource endpoint, not the full URL. Passing https://myreader.cognitiveservices.azure.com/ instead of myreader will cause a launch failure.
3. HTML content without setting mimeType: If you're passing HTML-formatted content, you must set mimeType: "text/html" in the chunk. Without it, your HTML tags will be read aloud literally by the text-to-speech engine.

Open your browser's developer tools (F12), go to the Console tab, and look for errors from the immersive-reader-sdk script. A successful launch will fire a DOM event and load the iframe. If you see the iframe appear in the Elements tab but it's blank or showing an error page, the problem has moved from SDK configuration to either cookie policy or network, covered in the next steps.

This is the one that trips up developers who have everything else configured perfectly. Azure AI Immersive Reader works by displaying a cross-origin iframe from Microsoft's infrastructure on top of your web application. Modern browsers, especially Safari, Firefox with Enhanced Tracking Protection, and Chrome with strict site isolation, will block third-party cookies inside that iframe, which prevents the reader's session from initializing correctly.

The Immersive Reader SDK has a built-in cookie policy API for exactly this reason. You can configure it to work within your application's cookie consent framework. In your SDK options, set the cookiePolicy field:

import { launchAsync, CookiePolicy } from "@microsoft/immersive-reader-sdk";

const options = {
  uiLang: "en",
  cookiePolicy: CookiePolicy.Enable  // or CookiePolicy.Disable
};

If you set CookiePolicy.Disable, the reader will run without persisting any user preferences between sessions, things like preferred font size and line spacing will reset each time. This is a reasonable tradeoff in environments where you can't guarantee cookie consent. Setting it to CookiePolicy.Enable requires that your user has given appropriate cookie consent first, which you're responsible for capturing and storing.

For iframe-specific browser blocking, check these browser-level settings:

• Chrome: Navigate to chrome://settings/content/cookies and check whether "Block third-party cookies" is enabled. In enterprise deployments, this may be enforced via Group Policy.
• Safari: Go to Safari → Preferences → Privacy and check "Prevent cross-site tracking." If this is on, Immersive Reader's iframe session management will break.
• Firefox: In about:preferences#privacy, check whether Enhanced Tracking Protection is set to Strict mode, that mode blocks cross-site cookies by default.

In enterprise environments, if browsers are managed via Intune or Active Directory Group Policy, you may need to add Microsoft's Immersive Reader domains to the browser's trusted sites or cookie exceptions list. The reader loads content from *.cognitiveservices.azure.com and reader.microsoft.com, both need to be accessible and trusted.

After adjusting cookie settings, do a full hard refresh (Ctrl+Shift+R) rather than a normal refresh. This clears cached responses that may include failed preflight CORS checks from your previous attempts.

So the iframe loads and the reader opens, but specific features like Read Aloud, translation, or syllable splitting aren't working. These are feature-level failures, and they have their own set of causes distinct from the launch problems covered above.

Read Aloud (text-to-speech) not working: The Azure AI Immersive Reader's speech synthesis feature uses Microsoft's Azure Speech service under the hood. If text-to-speech isn't working, first confirm that the lang tag in your content chunk matches a supported language tag. The service supports an extensive list of languages, for instance, Hindi is hi-IN, Brazilian Portuguese is pt-BR, and Japanese is ja-JP. Passing a language tag that isn't in the supported list, or passing an incorrect format, will cause the Read Aloud button to appear but produce no audio.

You can configure Read Aloud options explicitly in the SDK:

const options = {
  uiLang: "en",
  readAloudOptions: {
    autoplay: false,
    muted: false,
    scrollBehavior: 1  // 1 = scroll to word being read
  }
};

Translation not working: Immersive Reader supports real-time translation into a wide range of languages. If translation isn't appearing, verify two things: first, that your content chunk has a source language set (the lang field). Second, that you haven't inadvertently set translation options that conflict, for example, requesting translation into the same language as the source will silently produce no result.

To configure translation behavior:

const options = {
  translationOptions: {
    language: "es",           // Target translation language
    autoEnableDocumentTranslation: true,
    autoEnableWordTranslation: false
  }
};

Math display not working: If your content contains LaTeX or MathML and the math isn't rendering, you need to explicitly set the mimeType in the content chunk. For MathML, use "application/mathml+xml". The reader won't auto-detect math content, you have to tell it what it's getting.

After making changes to content or options, always test in an incognito or private browser window to rule out extension interference. Ad blockers, privacy extensions, and some password manager extensions have been known to intercept or block the requests that Immersive Reader makes to the backend service.