Debug logging for Nutrient Web SDK

Nutrient Web SDK includes opt-in debug logging for NutrientViewer.load(). When you enable it, the SDK prints a tagged console.log line for each initialization stage.

Use debug logging when a load hangs, throws an unexpected error, or never resolves. The console output shows the last stage the SDK reached, which helps you identify whether the issue comes from SDK initialization, worker loading, WebAssembly setup, document loading, rendering, or your application environment.

This guide explains how to:

• Enable debug logging for one load
• Enable debug logging globally
• Read the stage lines
• Interpret common failure patterns
• Decide what to include in a bug report

Enable debug logging

You can enable debug logging for one load() call or for every load after the SDK module evaluates.

Enable debug logging for one load

Pass logLevel: 'debug' or NutrientViewer.LogLevel.DEBUG in the configuration object you pass to NutrientViewer.load():

NutrientViewer.load({
  document: "/example.pdf",
  container: "#nutrient-viewer",
  logLevel: NutrientViewer.LogLevel.DEBUG,
});

This setting applies only to that load() call. Use it when you can edit the call site and need logs for a specific viewer instance.

Enable debug logging globally

Set globalThis.NUTRIENT_LOG_LEVEL = 'debug' before the SDK module evaluates:

<script>
  window.NUTRIENT_LOG_LEVEL = "debug";
</script>
<script src=".../nutrient-viewer.js"></script>

For dynamic imports, set the global before importing the SDK.

window.NUTRIENT_LOG_LEVEL = "debug";
await import("@nutrient-sdk/viewer");

The global setting applies to every later load() call. It also prints a sentinel line when the SDK entry module starts evaluating. That sentinel helps diagnose failures that happen before your code reaches NutrientViewer.load().

Set the global variable before the SDK loads

Set the global variable before the SDK entry module evaluates. If you set it after the SDK has loaded, debug logging won’t start for the already evaluated module.

For example, pasting window.NUTRIENT_LOG_LEVEL = 'debug' into DevTools and then calling location.reload() won’t work. Reloading discards the global variable before the SDK module evaluates again.

To toggle the global variable from DevTools, use one of these approaches:

• Navigate to a URL with a query parameter you control, and read that parameter in a script tag that runs before the SDK script tag.
• Use a browser extension that injects the variable at page-load time.

Read the log lines

When debug logging is on, the browser console shows stage lines like these:

[Nutrient #1] load() entered
[Nutrient #1] validating configuration
[Nutrient #1] configuration validated
[Nutrient #1] worker spawned
[Nutrient #1] chunk fetched: standalone
[Nutrient #1] backend selected: standalone
[Nutrient #1] React mounted
[Nutrient #1] WASM instantiated
[Nutrient #1] document opened
[Nutrient #1] load() resolved
[Nutrient #1] initial render complete

Line prefix and counter

Each per-load line uses a [Nutrient #N] prefix. #N increments with each NutrientViewer.load() call in the current page session.

Use the counter to distinguish concurrent loads. For example, loadTextComparison() runs two load() calls in parallel, so the console can show [Nutrient #1] and [Nutrient #2] lines interleaved.

The counter only indicates order within the current page session. A page reload resets it.

Stages

A successful load can include the following stages. The order can vary based on the backend and whether the browser has already cached the chunk.

Keep these ordering details in mind:

• chunk fetched: standalone changes to chunk cached: standalone on later standalone loads when the backend module has already been imported. The same applies after NutrientViewer.preloadWorker() has run. Each standalone load shows one of those two stages.
• initial render complete fires after document opened, but its position relative to load() resolved depends on the environment. In standalone mode, it can interleave with post-connect() setup. In server mode, it usually appears after load() resolved.

Failed loads

If a load fails, the SDK prints a final failed during init line:

[Nutrient #1] failed during init { lastStage: 'WASM instantiated', error: PSPDFKitError: ... }

lastStage shows the stage the SDK reached before the failure. The error field contains the original Error object, so DevTools can show the full stack trace.

Aborted loads

If an AbortSignal cancels a load, the SDK prints one final aborted by signal line.

[Nutrient #1] aborted by signal { lastStage: 'React mounted' }

The SDK logs the abort once. It doesn’t print a separate failed during init line for the same load. It also suppresses teardown errors and stage lines from callbacks that finish after the abort.

SDK module evaluated sentinel

When you enable the global setting before the SDK loads, the SDK prints one additional line at the top of its entry module:

[Nutrient] SDK module evaluated

This line doesn’t include a #N counter because it fires before any NutrientViewer.load() call. The SDK emits it before any other code in the entry module runs.

Use the sentinel to identify whether the SDK entry module evaluated:

• If you see [Nutrient] SDK module evaluated, the SDK entry module evaluated. If loading still fails or hangs, inspect the per-load [Nutrient #N] stage lines that follow.
• If you don’t see [Nutrient] SDK module evaluated, the SDK entry module didn’t evaluate. Look upstream of the SDK. Common causes include build-tool errors, failed chunk loads, and dynamic import() calls that never settle.

The sentinel helps expose silent failures where execution never reaches NutrientViewer.load().

Common failure patterns

The following patterns describe common console output and where to investigate next.

No logs appear

You set globalThis.NUTRIENT_LOG_LEVEL = 'debug' before the SDK loads and reload the page, but the console remains empty. You don’t see the sentinel or any stage lines.

This means the SDK entry module didn’t evaluate. An upstream layer prevented the SDK from reaching its first executable line.

Check the following areas:

• Open the browser Network tab and confirm nutrient-viewer.js and its chunks loaded with a 200 status.
• Check the console for parse errors or SyntaxError entries that appeared before your script tag ran. Some bundlers can transform the UMD bundle into syntax older parsers reject. One known case is Turbopack UMD re-minification in Next.js 16, which can produce invalid new Foo?.() optional-chain expressions that V8 rejects at parse time.
• Confirm the dynamic import() of the SDK resolved. If the import promise never resolves or rejects, a surrounding try/catch won’t run.

Logs stop and load never resolves

You see stage lines up to one point, and then logging stops. You don’t see failed during init, aborted by signal, or load() resolved.

This means an await in the SDK initialization flow is hanging without rejecting. Use the last visible stage to identify the boundary where initialization stopped.

Check the relevant area based on the last visible stage:

• Stopped at worker spawned — The standalone backend chunk’s dynamic import is hanging. Check the Network tab for an in-flight request for the nutrient-viewer-standalone.*.js chunk, and confirm your baseUrl is reachable.
• No stage lines after [Nutrient] SDK module evaluated — A pending NutrientViewer.preloadWorker() call may be hanging on the worker fetch, and load() is waiting for it. Confirm the worker file is reachable from the page’s origin.
• Stopped at WASM instantiated — The engine initialized, but document opened didn’t fire. The document fetch is hanging. Confirm the document URL responds. In server-backed deployments, confirm documentId is valid and the JWT hasn’t expired.
• Stopped at document opened — The document parsed, but post-load setup is stuck. This setup can include the annotation provider, form fields, optional content group (OCG) layers, or embedded files. Check the Network tab for in-flight requests.
• Stopped at load() resolved — load() resolved, but initial render complete didn’t fire. The React tree mounted, but canvas rendering is stuck. Confirm the container has nonzero dimensions and isn’t display: none.

Read the failure stack trace

The failed during init line includes the original Error object. Expand it in DevTools to view the full stack trace.

Use the stack trace this way:

• Frames near the top usually come from Nutrient Web SDK.
• Frames near the bottom usually come from your application.
• The message field usually gives the most actionable detail.

If the message reads Failed to initialize PSPDFKit: Invalid license key, check the license string, the activation domain, and whether the environment can reach the activation server.

If the message names a file, such as Couldn't fetch the file: Not Found, check the URL, server response, and cross-origin resource sharing (CORS) headers.

Performance impact

Debug logging is opt-in and off by default.

When logging is off, each stage call only performs one truthiness check. The SDK doesn’t allocate logging data, call the console, or produce console output.

When logging is on, the main cost comes from console.log calls and browser console rendering. You can leave the global setting enabled during a production debug session.

File a bug report

If debug logging identifies a failure pattern, include the full console output in your bug report. Useful output includes:

• A failed during init line with the stack trace
• A hung load with the last visible stage
• An absent SDK-module-evaluated sentinel
• Relevant Network tab failures

For more information, refer to the bug reporting guide.

Related guides

Use these guides with debug logging when you narrow down the failure area:

• For support requests and diagnostic attachments, refer to the bug reporting guide.
• For common integration and rendering issues, refer to the common issues guide.
• For license activation failures, refer to the license troubleshooting guide.
• For asset chunk loading failures, refer to the ChunkLoadError troubleshooting guide.
• For configuration options used by NutrientViewer.load(), refer to the NutrientViewer.Configuration API reference.