mozilla/pdf.js · error · TypeError

First argument of app.setTimeOut must be a string

Error message

First argument of app.setTimeOut must be a string

What it means

app.setTimeOut schedules a one-shot PDF-JavaScript expression after nMilliseconds. PDF.js requires the first argument to be a code string (or object {cExpr, nMilliseconds}); if cExpr is not a string after unwrapping, a TypeError is thrown. This mirrors Acrobat JS semantics and protects the sandbox.

Source

Thrown at src/scripting_api/app.js:634

    }
    if (typeof nMilliseconds !== "number") {
      throw new TypeError(
        "Second argument of app.setInterval must be a number"
      );
    }
    const callbackId = this._registerTimeoutCallback(cExpr);
    this._externalCall("setInterval", [callbackId, nMilliseconds]);
    return this._registerTimeout(callbackId, true);
  }

  setTimeOut(cExpr, nMilliseconds = 0) {
    if (cExpr && typeof cExpr === "object") {
      nMilliseconds = cExpr.nMilliseconds || 0;
      cExpr = cExpr.cExpr;
    }

    if (typeof cExpr !== "string") {
      throw new TypeError("First argument of app.setTimeOut must be a string");
    }
    if (typeof nMilliseconds !== "number") {
      throw new TypeError("Second argument of app.setTimeOut must be a number");
    }
    const callbackId = this._registerTimeoutCallback(cExpr);
    this._externalCall("setTimeout", [callbackId, nMilliseconds]);
    return this._registerTimeout(callbackId, false);
  }

  trustedFunction() {
    /* Not implemented */
  }

  trustPropagatorFunction() {
    /* Not implemented */
  }
}

View on GitHub (pinned to 5903d58d58)

Solutions

Pass the expression as a string: app.setTimeOut('myFunc()', 500).
If using object form, include a string cExpr: {cExpr:'myFunc()', nMilliseconds:500}.
Avoid passing function references; the Acrobat JS scheduler evaluates code strings.

Example fix

// before
app.setTimeOut(() => { doX(); }, 500);
// after
app.setTimeOut('doX()', 500);

Defensive patterns

Strategy: type-guard

Validate before calling

// Validate cExpr is a string before calling app.setTimeOut.
function scheduleTimeout(app, cExpr, nMilliseconds = 0) {
  if (typeof cExpr !== 'string' || cExpr.length === 0) {
    throw new TypeError('cExpr must be a non-empty string');
  }
  return app.setTimeOut(cExpr, nMilliseconds);
}

Type guard

const isCodeString = (v) => typeof v === 'string' && v.trim().length > 0;

Try / catch

try { app.setTimeOut(maybeExpr, 500); }
catch (e) {
  if (!(e instanceof TypeError && /First argument of app\.setTimeOut/.test(e.message))) throw e;
  // fall back to no-op or host scheduler
}

Prevention

Acrobat JS app.setTimeOut takes a code string, never a function reference.
Validate input type before calling when values originate from user/form input.
Prefer the object form {cExpr, nMilliseconds} only when cExpr is a string.

When it happens

Trigger: Calling app.setTimeOut(myFunc, 500) where myFunc is a function reference, or object form {cExpr: 42}; the check at src/scripting_api/app.js:634 fails typeof cExpr !== 'string'.

Common situations: Authors transferring window.setTimeout(fn, ms) habits to the Acrobat API; passing undefined because the expression was thought optional; object-form missing cExpr.

Understand the failure class

Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

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