Base64URL decode fails: checklist (alphabet, padding, whitespace)

Base64URL quick map

Focus for this query

• Padding is required for many decoders: length must be divisible by 4.
• Strip whitespace first and check for characters outside [A-Za-z0-9_-].
• If this value came from a URL parameter, URL-decode first, then normalize Base64URL.

Safe decode workflow

1. Remove whitespace/newlines.
2. Normalize alphabet: -→+, _→/.
3. Add padding so length % 4 == 0.
4. Decode locally and validate output shape (JSON/text/binary).

Runtime snippet (generic)

function base64urlToBase64(input) {
  const s = String(input || '').replace(/\s+/g, '').replace(/-/g, '+').replace(/_/g, '/');
  return s + '='.repeat((4 - (s.length % 4)) % 4);
}

const b64 = base64urlToBase64(token);
const bytes = Uint8Array.from(atob(b64), (c) => c.charCodeAt(0));
const text = new TextDecoder().decode(bytes);
console.log(text);

Frequent failures

• Invalid character from copy/paste noise or wrong alphabet.
• Missing padding when decoder expects canonical Base64.
• JSON parse after decode fails when payload is not JSON/text.

Privacy guardrail

Base64/Base64URL strings can still contain secrets. Decode locally, redact sensitive fields, and only then share snippets.

FAQ

Is anything uploaded to a server? No. All processing happens locally in your browser. Files are never uploaded.

What is the recommended workflow? Validate the input, fix the first real issue, validate again, then export/convert. This avoids compounding errors.