How to fix invalid Base64: incorrect padding and length

Short answer

Do not fix a Base64 padding error by appending = at random. First identify whether the input is Base64 or Base64URL, remove only transport whitespace, and check its length. A length whose remainder modulo four is one is impossible; remainders two or three are recoverable only when the applicable profile allows padding to be omitted.

Quick padding decision table

Apply this table only to input with no existing = signs, after removing whitespace permitted by the transport. If padding is already present, validate it separately: TQ= is incomplete padding, not an unpadded value. Do not remove characters just to make the value fit.

This table restores the shape of an omitted-padding value. It does not prove that the alphabet, existing padding, trailing bits, decoded bytes, or expected content are valid.

What “incorrect padding” means

Base64 represents each three-byte group with four characters. When the final group contains one or two bytes, standard Base64 ends in == or =. The padding is not data. It records how many positions in the last group do not carry another byte.

SG9sYQ== therefore decodes to Hola, while SG9sYQ carries the same data without padding. The second form may be valid under a protocol that explicitly makes padding optional, but it is not a universal assumption. The Base64 and Base64URL converter lets you select the variant and checks the final form before producing text.

The error often appears as Python binascii.Error: Incorrect padding, Node or browser decoding failure, or a rejection from an API. The wording is broad: the real cause may be missing padding, an impossible length, the wrong Base64URL alphabet, misplaced =, or truncated data.

Diagnose the length

After ignoring whitespace accepted by the input interface, calculate length % 4:

• Remainder 0 can be complete, although its alphabet and trailing bits still need checking.
• Remainder 2 would need two = characters in a padded representation.
• Remainder 3 would need one = character.
• Remainder 1 cannot represent a complete Base64 block; information is missing or an extra character was introduced.

Never delete characters merely to change a remainder of one. That alters the byte sequence and can disguise truncated input.

Restore omitted padding without hiding corruption

Only normalize a value when the producer’s contract says that padding may be omitted. This JavaScript helper performs the length step and deliberately rejects the impossible remainder:

function restoreBase64Padding(input) {
  const compact = input.replace(/[\t\n\r ]/g, '');

  if (compact.includes('=')) {
    return compact; // Validate existing padding; do not rewrite it.
  }

  const remainder = compact.length % 4;
  if (remainder === 1) {
    throw new Error(
      'The Base64 value is truncated or contains an extra character.',
    );
  }

  return compact + '='.repeat((4 - remainder) % 4);
}

Run strict Base64 validation after this step. The helper does not choose an alphabet, validate characters, check canonical trailing bits, or prove that the resulting bytes are UTF-8 text. It permits ASCII spaces, tabs, CR, and LF, matching this site’s converter; omit that removal if your protocol forbids whitespace. A successful decode cannot prove that no data was lost in transit.

Check the alphabet before padding

Standard Base64 uses + and /; Base64URL uses - and _. Compact JWT segments normally use the URL-safe alphabet and omit padding. Replacing the two symbols without checking the source contract may accept data under the wrong rules.

Other invalid forms include = in the middle, more than two padding characters, or data after padding. Completing the length cannot repair these cases. Retrieve the original value or fix the producer instead.

Canonical trailing bits matter too

Two strings can appear to decode to the same bytes even though one has nonzero unused bits in its final character. RFC 4648 requires these pad bits to be zero for a canonical encoding. Strict validation prevents multiple spellings of the same bytes, which matters for signatures, cache keys, and exact comparisons.

A safe repair workflow

1. Keep an exact copy of the received input.
2. Confirm Base64 versus Base64URL and whether the protocol permits omitted padding.
3. Remove only transport whitespace, not characters inside the value.
4. Validate alphabet, padding position, length, and canonical trailing bits.
5. Decode the bytes, then validate UTF-8 separately if text is expected.

For an API, fixing the producer is usually safer than making every consumer guess. Consumer-side normalization is appropriate only when the protocol defines the unpadded form.

Quick examples

TQ== is standard Base64 for M; TQ can be accepted as Base64URL or under an unpadded profile. T=== has excessive padding, T=Q= places it incorrectly, and A has an impossible length. Libraries may report all of them as “incorrect padding,” so a precise diagnosis is more useful than adding equals signs until an error disappears.

Frequently asked questions

Can I always add two equals signs to Base64?

No. A remainder of two needs ==, a remainder of three needs =, and a remainder of zero needs neither. A remainder of one cannot be repaired by padding. Existing padding must also be in the correct final position.

Why does a multiple-of-four value still fail?

Length is only one rule. The value can still contain the wrong alphabet, padding in the middle, too much padding, nonzero unused bits, or bytes that do not match the expected content type. Validate each layer separately.

Why do JWT segments usually have no padding?

Compact JWT uses Base64URL under a profile that omits =. The missing padding can be reconstructed from the segment length, but that only decodes the bytes. It does not verify the JWT signature or trust its claims.