mozilla/pdf.js · error · Error

Cannot create sandbox.

Error message

Cannot create sandbox.

What it means

Thrown by FirefoxScripting.createSandbox when the host Firefox process returns a falsy value from the async 'createSandbox' request. It signals that the browser-side sandbox (used to execute interactive PDF JavaScript for form calculation/validation) could not be initialized. This code path only runs inside the Firefox PDF Viewer (MOZCENTRAL build), not in the generic web build.

Source

Thrown at web/firefoxcom.js:254

  })();
}

class FirefoxComDataRangeTransport extends PDFDataRangeTransport {
  requestDataRange(begin, end) {
    FirefoxCom.request("requestDataRange", { begin, end });
  }

  // NOTE: This method is currently not invoked in the Firefox PDF Viewer.
  abort() {
    FirefoxCom.request("abortLoading", null);
  }
}

class FirefoxScripting {
  static async createSandbox(data) {
    const success = await FirefoxCom.requestAsync("createSandbox", data);
    if (!success) {
      throw new Error("Cannot create sandbox.");
    }
  }

  static async dispatchEventInSandbox(event) {
    FirefoxCom.request("dispatchEventInSandbox", event);
  }

  static async destroySandbox() {
    FirefoxCom.request("destroySandbox", null);
  }
}

class MLManager {
  #abortSignal = null;

  #enabled = null;

  #eventBus = null;

View on GitHub (pinned to 5903d58d58)

Solutions

  1. Verify the PDF actually requires a scripting sandbox; if it has no JS actions the failure is benign and can be ignored.
  2. Ensure the Firefox host (browser chrome) handles 'createSandbox' requests and is the correct MOZCENTRAL build matching this pdf.js version.
  3. If building/embedding, confirm the data object passed to createSandbox is the serialized sandbox settings the host expects.
  4. Catch the error in the dispatch layer and degrade gracefully (forms render without JS-driven behaviors).

Example fix

// before
await FirefoxScripting.createSandbox(data);

// after - guard host availability and degrade gracefully
try {
  await FirefoxScripting.createSandbox(data);
} catch (e) {
  console.warn('Sandbox unavailable; interactive JS disabled:', e.message);
}
Defensive patterns

Strategy: try-catch

Validate before calling

// Cannot validate host availability from JS; guard the call site.
const canCreateSandbox = typeof FirefoxCom !== 'undefined' && typeof FirefoxCom.requestAsync === 'function';

Type guard

function isSandboxCapable(host) {
  return host && typeof host.requestAsync === 'function';
}

Try / catch

try {
  await FirefoxScripting.createSandbox(data);
} catch (e) {
  if (e.message === 'Cannot create sandbox.') {
    // Degrade: render forms without JS execution.
    console.warn('PDF scripting sandbox unavailable.');
  } else {
    throw e;
  }
}

Prevention

When it happens

Trigger: Calling FirefoxScripting.createSandbox(data) where FirefoxCom.requestAsync('createSandbox', data) resolves to a falsy value (false/undefined/null). This happens when the host chrome-privileged handler rejects or fails to set up the sandbox for an interactive PDF with JavaScript actions.

Common situations: Opening a PDF with AcroForm/JavaScript actions in a Firefox build where the scripting host is unavailable, disabled, or where the data payload (sandbox configuration) is malformed. Also seen during Firefox version mismatches where the host message contract changed.

Related errors

AI-assisted analysis of mozilla/pdf.js@5903d58d58 (2026-08-13). Data as JSON: /api/errors/7455765f45dd0929. Report an issue: GitHub.