maotoumao/MusicFree · error · Error

'atob' failed: The string to be decoded is not correctly enc

Error message

'atob' failed: The string to be decoded is not correctly encoded.

What it means

The pure-JS atob polyfill in src/utils/base64.ts throws this when the input, after stripping trailing '=' padding, has length % 4 === 1 — an impossible base64 length indicating corrupted or truncated input. It guards the decoder from garbage strings.

Source

Thrown at src/utils/base64.ts:37

            if (charCode > 0xff) {
                throw new Error(
                    "'btoa' failed: The string to be encoded contains characters outside of the Latin1 range.",
                );
            }

            block = (block << 8) | charCode;
        }

        return output;
    },

    atob: (input: string = "") => {
        let str = input.replace(/[=]+$/, "");
        let output = "";

        if (str.length % 4 == 1) {
            throw new Error(
                "'atob' failed: The string to be decoded is not correctly encoded.",
            );
        }
        for (
            let bc = 0, bs = 0, buffer, i = 0;
            (buffer = str.charAt(i++));
            ~buffer && ((bs = bc % 4 ? bs * 64 + buffer : buffer), bc++ % 4)
                ? (output += String.fromCharCode(255 & (bs >> ((-2 * bc) & 6))))
                : 0
        ) {
            buffer = chars.indexOf(buffer);
        }

        return output;
    },
};

export default Base64;

View on GitHub (pinned to d118b18b3d)

Solutions

Validate/repair the input before decoding: strip whitespace, ensure length % 4 !== 1, re-add padding.
If the source uses URL-safe base64, convert '-'→'+', '_'→'/' before atob.
Re-export/copy the original encoded string (it was truncated in transit, so regenerate it).
Wrap atob in try/catch and surface a user-friendly 'data is corrupted' message.

Example fix

// before
const decoded = atob(input);
// after
const normalized = input.replace(/\s+/g, '').replace(/-/g, '+').replace(/_/g, '/');
const padded = normalized + '='.repeat((4 - (normalized.length % 4)) % 4);
const decoded = atob(padded);

Defensive patterns

Strategy: validation

Validate before calling

function isProbablyBase64(s) {
  const str = s.replace(/\s+/g, '').replace(/[=-]+$/, '');
  return /^[A-Za-z0-9+/]*$/.test(str) && str.length % 4 !== 1;
}
if (!isProbablyBase64(input)) throw new Error('not valid base64');

Try / catch

try {
  return atob(input);
} catch (e) {
  if (String(e).includes('not correctly encoded')) {
    throw new Error('备份内容已损坏，请重新导出'); // surface friendly message
  }
  throw e;
}

Prevention

Strip whitespace and normalize URL-safe characters (-, _) before decoding.
Validate length % 4 !== 1 and character set before calling atob.
Never hand-edit base64 payloads; re-export instead.
When passing base64 in URLs, use encodeURIComponent to avoid + being read as space.

When it happens

Trigger: Calling atob() with a string that is not valid base64: truncated clipboard/import payload, URL-safe base64 (contains '-'/'_') passed to the standard decoder, extra whitespace/newlines shifting length, or decoding a value that was never base64 at all.

Common situations: Restoring a backup from a URL where the base64 was cut off or query-param-mangled (+ turned into space); sharing encoded plugin data across apps that url-encode it; hand-edited base64 strings.

Related errors

'btoa' failed: The string to be encoded contains characters

AI-assisted analysis of maotoumao/MusicFree@d118b18b3d (2026-08-30). Data as JSON: /api/errors/ea7164f9abed320c. Report an issue: GitHub.