OrchardCMS/OrchardCore · error · TypeError

@@toPrimitive must return a primitive value.

Error message

@@toPrimitive must return a primitive value.

What it means

This TypeError is thrown by the Babel _toPrimitive helper inlined into the compiled FontAwesome v4-shims bundle. The helper converts an object used as a property key via Symbol.toPrimitive; if that method returns an object instead of a primitive, the spec requires throwing this TypeError. It is a runtime error from transpiled ES2015+ code, not from FontAwesome logic itself.

Solutions

  1. Do not return an object from Symbol.toPrimitive; return a string, number, bigint, boolean, or symbol
  2. Remove any custom polyfill overriding Symbol.toPrimitive behavior that violates the spec
  3. Re-restore the pristine v4-shims.js from the fontawesome-free-6.7.2 distribution if the bundle was modified
  4. Verify your build does not re-transpile vendor bundles with a broken helpers plugin

Example fix

// before
const bad = { [Symbol.toPrimitive](hint) { return {}; } };
const obj = { [bad]: 1 }; // TypeError: @@toPrimitive must return a primitive value.
// after
const good = { [Symbol.toPrimitive](hint) { return 'key'; } };
const obj2 = { [good]: 1 };
Defensive patterns

Strategy: validation

Validate before calling

function isSafeKey(k) { return typeof k === 'string' || typeof k === 'symbol' || typeof k === 'number'; }

Type guard

function hasCompliantToPrimitive(o) { return !(o && typeof o === 'object' && typeof o[Symbol.toPrimitive] === 'function' && (() => { try { const v = o[Symbol.toPrimitive]('default'); return typeof v !== 'object'; } catch { return false; } })()); }

Try / catch

try { obj[key] = value; } catch (e) { if (e instanceof TypeError && e.message.includes('@@toPrimitive')) { console.error('Bad key:', key); } else { throw e; } }

Prevention

When it happens

Trigger: An object whose Symbol.toPrimitive method returns an object (e.g. `{ [Symbol.toPrimitive](hint){ return {} } }`) is used where a primitive is required, such as a property key via _toPropertyKey in compiled code.

Common situations: Usually seen when mixing a mis-patched/broken polyfill or corrupted vendor bundle into the page; very rarely hit intentionally by app code that defines a non-compliant Symbol.toPrimitive. In Orchard Core it surfaces only when the v4-shims.js bundle is executed against object keys.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

AI-assisted analysis of OrchardCMS/OrchardCore@4306c0717f (2026-09-13). Data as JSON: /api/errors/873e96d1bc13f96b. Report an issue: GitHub.

Appendix: source

Thrown at src/OrchardCore.Modules/OrchardCore.Resources/wwwroot/Vendor/fontawesome-free-6.7.2/js/v4-shims.js:62

  }
  function _objectSpread2(e) {
    for (var r = 1; r < arguments.length; r++) {
      var t = null != arguments[r] ? arguments[r] : {};
      r % 2 ? ownKeys(Object(t), !0).forEach(function (r) {
        _defineProperty(e, r, t[r]);
      }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(e, Object.getOwnPropertyDescriptors(t)) : ownKeys(Object(t)).forEach(function (r) {
        Object.defineProperty(e, r, Object.getOwnPropertyDescriptor(t, r));
      });
    }
    return e;
  }
  function _toPrimitive(t, r) {
    if ("object" != typeof t || !t) return t;
    var e = t[Symbol.toPrimitive];
    if (void 0 !== e) {
      var i = e.call(t, r || "default");
      if ("object" != typeof i) return i;
      throw new TypeError("@@toPrimitive must return a primitive value.");
    }
    return ("string" === r ? String : Number)(t);
  }
  function _toPropertyKey(t) {
    var i = _toPrimitive(t, "string");
    return "symbol" == typeof i ? i : i + "";
  }

  var S = {
      classic: {
        fa: "solid",
        fas: "solid",
        "fa-solid": "solid",
        far: "regular",
        "fa-regular": "regular",
        fal: "light",
        "fa-light": "light",
        fat: "thin",

View on GitHub (pinned to 4306c0717f)