zloirock/core-js · error · TypeError

Incorrect `lastChunkHandling` option

Error message

Incorrect `lastChunkHandling` option

What it means

Uint8Array.fromBase64 (core-js polyfill) validates the lastChunkHandling option against the allowed set: 'loose' (default), 'strict', and 'stop-before-partial'. Any other value — including typos, wrong casing, or non-string values — throws this TypeError before decoding begins.

Source

Thrown at packages/core-js/internals/uint8-from-base64.js:81

var writeBytes = function (bytes, elements, written) {
  var elementsLength = elements.length;
  for (var index = 0; index < elementsLength; index++) {
    bytes[written + index] = elements[index];
  }
  return written + elementsLength;
};

/* eslint-disable max-statements, max-depth -- TODO */
module.exports = function (string, options, into, maxLength) {
  aString(string);
  anObjectOrUndefined(options);
  var alphabet = getAlphabetOption(options) === 'base64' ? base64Alphabet : base64UrlAlphabet;
  var lastChunkHandling = options ? options.lastChunkHandling : undefined;

  if (lastChunkHandling === undefined) lastChunkHandling = 'loose';

  if (lastChunkHandling !== 'loose' && lastChunkHandling !== 'strict' && lastChunkHandling !== 'stop-before-partial') {
    throw new TypeError('Incorrect `lastChunkHandling` option');
  }

  if (into) notDetached(into.buffer);

  var stringLength = string.length;
  var bytes = into || $Array(floor(stringLength * 3 / 4));
  var written = 0;
  var read = 0;
  var chunk = '';
  var index = 0;

  if (maxLength) while (true) {
    index = skipAsciiWhitespace(string, index);
    if (index === stringLength) {
      if (chunk.length > 0) {
        if (lastChunkHandling === 'stop-before-partial') {
          break;
        }

View on GitHub (pinned to 84e45fba09)

Solutions

1. Use exactly one of: 'loose', 'strict', 'stop-before-partial' (case-sensitive).
2. Remove the option entirely to get the 'loose' default.
3. Validate/normalize user-supplied options before passing them in.
4. Add a TypeScript union type: `type LastChunkHandling = 'loose' | 'strict' | 'stop-before-partial'`.

Example fix

// before
Uint8Array.fromBase64(b64, { lastChunkHandling: 'Strict' }); // TypeError
// after
Uint8Array.fromBase64(b64, { lastChunkHandling: 'strict' });

const VALID = ['loose', 'strict', 'stop-before-partial'];
const lch = options?.lastChunkHandling;
if (lch !== undefined && !VALID.includes(lch)) {
  throw new TypeError(`lastChunkHandling must be one of ${VALID.join(', ')}`);
}

function isLastChunkHandling(v) {
  return v === undefined || v === 'loose' || v === 'strict' || v === 'stop-before-partial';
}

try {
  bytes = Uint8Array.fromBase64(b64, opts);
} catch (e) {
  if (e instanceof TypeError && /lastChunkHandling/.test(e.message)) {
    bytes = Uint8Array.fromBase64(b64); // default 'loose'
  } else throw e;
}

When it happens

Trigger: `Uint8Array.fromBase64(s, { lastChunkHandling: 'Strict' })`, `{ lastChunkHandling: 'ignore' }`, `{ lastChunkHandling: null }` (distinct from undefined) — any value not exactly one of the three accepted strings.

Common situations: Copying option names from other base64 libraries, TypeScript types absent so a typo compiles, camelCase/snake_case drift ('last_chunk_handling'), or passing user-supplied config straight into the options object.

Understand the failure class

Background: Invalid option value errors: "must be one of", "is not a valid", and "only allows" failures explained — this error's family across 23 libraries.

Related errors

• Cannot convert a Symbol value to a string
• Extra bits
• Malformed padding: exactly one additional character
• Missing padding
• ArrayBuffer expected

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