What causes "Cannot convert a Symbol value to a string" in zloirock/core-js?

Use `String(sym)` or `sym.description` when you explicitly want the symbol's text.

zloirock/core-js · error · TypeError

Cannot convert a Symbol value to a string

Error message

Cannot convert a Symbol value to a string

What it means

core-js's to-string helper (used by String.prototype polyfills, template handling, etc.) deliberately rejects Symbol arguments instead of implicitly converting them. Per spec, operations like `String(sym)` are allowed but many abstract ToString operations must throw when given a Symbol; this helper enforces that. It exists so polyfilled string coercions match the spec and fail loudly rather than producing '[object Symbol]'.

Source

Thrown at packages/core-js/internals/to-string.js:7

'use strict';
var classof = require('../internals/classof');

var $String = String;

module.exports = function (argument) {
  if (classof(argument) === 'Symbol') throw new TypeError('Cannot convert a Symbol value to a string');
  return $String(argument);
};

View on GitHub (pinned to 84e45fba09)

Solutions

Use `String(sym)` or `sym.description` when you explicitly want the symbol's text.
Check the argument being passed is actually a string, not a Symbol.
If you want spec-compliant implicit conversion, use template literals `${sym}` only when the operation allows it (template literals throw too — prefer sym.description).

Example fix

// before
const key = Symbol('id');
console.log(key.padStart(10)); // TypeError
// after
console.log(String(key.description).padStart(10));

Defensive patterns

Strategy: type-guard

Validate before calling

if (typeof value === 'symbol') throw new TypeError('Expected a string, got a Symbol');

Type guard

function isStringable(v) { return typeof v !== 'symbol'; }

Try / catch

try {
  doStringOp(value);
} catch (e) {
  if (e instanceof TypeError && /Symbol/.test(e.message)) {
    doStringOp(String(value.description ?? ''));
  } else throw e;
}

Prevention

Use sym.description when you want a Symbol's text.
Type-check arguments at API boundaries for typeof 'string'.
Never implicitly concatenate Symbols into strings.

When it happens

Trigger: Calling any core-js-polyfilled string-based API with a Symbol argument, e.g. `sym.trim()`, `sym.padStart(5)`, `sym.split('')`, or polyfilled `parseInt(sym)`, `alert(sym)` — anything that routes through to-string.js.

Common situations: Using a Symbol as an object property in string interpolation contexts, passing a well-known Symbol (like Symbol.iterator) where a string was expected, accidental argument-order mistakes, or template building that concatenates symbols.

Related errors

AI-assisted analysis of zloirock/core-js@84e45fba09 (2026-08-30). Data as JSON: /api/errors/39f0d7a2e4476fd0. Report an issue: GitHub.