🚨 Microsoft Teams Error: 'The library has not yet been initialized' — Cause, Fix, and Troubleshooting Guide

What this error means

You call a Teams JavaScript SDK API — app.getContext(), authentication.getAuthToken(), or similar — and it throws or rejects with an SdkError:

The library has not yet been initialized

The SDK requires that app.initialize() be called and awaited before any other API. initialize() performs a handshake with the Teams host over postMessage; until that handshake resolves, the library has no context and every call fails with the notInitialized error. There are two ways to hit this: calling an API before initialize() has resolved, or running the page outside a Teams host entirely (a plain browser tab), where nothing answers the handshake so initialization never completes.

What users report

• The first SDK call after page load throws The library has not yet been initialized.
• The app works when embedded in Teams but fails when the same URL is opened in a normal browser tab.
• getContext() or getAuthToken() fails while initialize() is still pending because it was not awaited.
• Intermittent failures under slow networks, where the handshake resolves after the first API call fires.
• The page appears blank or hangs in a browser because initialize() never resolves outside a host.
• Console shows the SDK notInitialized condition preceding any auth or context error.

Tenant and app configuration causes

• API called before initialize resolves. app.initialize() returns a promise; calling other APIs without awaiting it runs them too early.
• initialize() never called. The code path that renders the component skipped initialization entirely.
• Page loaded standalone. Opened in a raw browser tab with no Teams host, the handshake has no responder and never completes.
• CSP or iframe blocking. A restrictive Content-Security-Policy or X-Frame-Options prevents the page from being framed by Teams, so the postMessage handshake fails.
• Domain not in validDomains. If the page’s domain is not allowed in the manifest, the host will not communicate with the frame and initialization stalls.
• Race in a framework lifecycle. A component effect fires an API call in parallel with, rather than after, the initialize promise.

Confirming tenant configuration

Confirm the ordering. Wrap initialization in an explicit await and log both sides:

import { app, authentication } from "@microsoft/teams-js";

async function boot() {
  console.log("initializing...");
  await app.initialize();
  console.log("initialized");

  const context = await app.getContext();
  console.log("context:", context);
}

boot().catch((err) => console.error("boot failed:", err));

If you see context: logged, ordering is correct. If boot failed: fires with the not-initialized message, an API ran before await app.initialize() completed.

Test where it runs. Load the page inside the Teams client (as a tab or in the developer portal preview), not as a standalone browser tab. Outside a host, app.initialize() will not resolve because there is no host to answer the handshake — that alone explains “works in Teams, hangs in a browser.”

Check framing and domains. In the browser dev tools, look for CSP or X-Frame-Options errors in the console when Teams tries to frame the page, and confirm the page host is present in validDomains in manifest.json.

Resolution

Await app.initialize() before any other SDK call, and gate the rest of your app on a readiness flag so nothing races the handshake:

import { app } from "@microsoft/teams-js";

let ready = false;

export async function ensureTeams() {
  if (ready) return;
  await app.initialize();
  ready = true;
}

// Every entry point calls ensureTeams() first:
export async function loadContext() {
  await ensureTeams();
  return app.getContext();
}

Detect standalone vs embedded so the page degrades gracefully when it is not inside Teams. Race the initialize promise against a timeout and show a “open this inside Teams” message instead of hanging:

async function initWithTimeout(ms = 3000) {
  const timeout = new Promise((_, reject) =>
    setTimeout(() => reject(new Error("not-in-teams")), ms),
  );
  await Promise.race([app.initialize(), timeout]);
}

initWithTimeout()
  .then(() => renderApp())
  .catch(() => renderStandaloneNotice());

Fix the environment so the host can talk to the frame: allow Teams to embed the page (do not send a blocking X-Frame-Options, and set a CSP frame-ancestors that permits the Teams domains), and list the page’s domain in validDomains in the manifest. Without both, the handshake cannot complete and initialization stays pending.

Avoiding tenant drift

• Always await initialize first. Treat app.initialize() as a hard prerequisite for every other SDK call.
• Use one readiness gate. A single guarded init function prevents scattered calls from racing the handshake.
• Do not test in a raw browser. Outside a Teams host the handshake never completes; validate inside the client or developer portal.
• Keep the page embeddable. Blocking X-Frame-Options or a strict CSP silently breaks initialization.
• Register the domain. The page host must be in validDomains or the host will not communicate with the frame.
• Handle the not-in-Teams case. Time out initialization and show guidance rather than hanging on a page that will never initialize.

Related tenant errors

• Manifest Validation Failed
• Adaptive Card Render Failure
• 403 Authorization_RequestDenied