How to Solve binascii.Error: Incorrect padding with Base64 in Python

The binascii.Error: Incorrect padding error occurs when you try to decode a Base64-encoded string that has incorrect or missing padding. Base64 encoding requires the input to have a length that's a multiple of 4.

This guide explains the cause of this error and demonstrates how to fix it by correctly padding the input string, validating input, and using the appropriate decoding methods.

Understanding Base64 Padding

Base64 encoding converts binary data into an ASCII string format. The encoding process groups every 3 bytes (24 bits) of input into 4 Base64 characters. If the input data's length isn't a multiple of 3, padding is added using = characters so that the output length is a multiple of 4.

• Valid Base64 strings have a length that is a multiple of 4. If the length is not a multiple of 4, it's likely missing padding.
• Padding characters (=) can only appear at the end of the encoded string. They are used to fill out the last block to 4 characters.

Fixing Incorrect Padding

The core solution is to ensure the Base64 string has the correct padding before decoding.

Adding Padding Manually

import base64
import re

def decode_base64(encoded_bytes, altchars=b'+/'):
    # 1. Remove any invalid characters:
    encoded_bytes = re.sub(rb'[^a-zA-Z0-9%s]+' % altchars, b'', encoded_bytes)

    # 2. Calculate missing padding:
    missing_padding = len(encoded_bytes) % 4

    # 3. Add padding if needed:
    if missing_padding:
        encoded_bytes += b'=' * (4 - missing_padding)

    # 4. Decode, handling potential errors
    try:
        return base64.b64decode(encoded_bytes, altchars=altchars)
    except base64.binascii.Error as e:
        print(f"Decoding error: {e}")
        return None  # Or raise the exception, depending on your needs

# Example Usage
data = bytes('{"name": "Clark Kent"}', encoding='utf-8')
encoded_bytes = base64.b64encode(data)
print(encoded_bytes)  # Output: b'eyJuYW1lIjogIkNsYXJrIEtlbnQifQ=='

# Simulate missing padding
bytes_without_padding = encoded_bytes[:-2]  # Remove the last two characters (padding)

# Decode with padding correction:
decoded_bytes = decode_base64(bytes_without_padding)
print(decoded_bytes) # Output: b'{"name": "Clark Kent"}'

print(data == decoded_bytes) # Output: True

#Example with original
print(base64.b64decode(bytes_without_padding + b'==')) # Output: b'{"name": "Clark Kent"}'

decode_base64(encoded_bytes, altchars=b'+/'): This function now correctly handles padding.

• Step 1: Remove Invalid Characters:.
  • The regex r'[^a-zA-Z0-9%s]+' % altchars matches any character except the characters from a-zA-Z0-9 charset, as well as the characters defined in the altchars parameter.
  • The re.sub method removes these characters, as they are not base64 characters.
• Step 2: Calculate Missing Padding: missing_padding = len(encoded_bytes) % 4. This determines how many = characters are needed. The result will be 0, 1, 2, or 3. If it's 0, no padding is needed.
• Step 3: Add Padding: encoded_bytes += b'=' * (4 - missing_padding). We append the correct number of = characters.
• Step 4: Decode and handle exceptions. The base64.b64decode() method decodes the encoded bytes. If an error occurs during decoding, an exception is caught.

Handling Invalid Characters

The decode_base64 function above includes a crucial step: re.sub(rb'[^a-zA-Z0-9%s]+' % altchars, b'', encoded_bytes). This removes any non-Base64 characters before attempting to decode. This is important because invalid characters can also cause padding errors, even if the = padding is technically correct.

Using base64.urlsafe_b64decode() Correctly

The base64.urlsafe_b64decode() function is used for Base64 strings that have been encoded using the URL-safe alphabet (- and _ instead of + and /). It also requires correct padding. You can use the same decode_base64 function above, but must pass the correct altchars value:

import base64
import re

def decode_base64(encoded_bytes, altchars=b'+/'):
    # 1. Remove any invalid characters:
    encoded_bytes = re.sub(rb'[^a-zA-Z0-9%s]+' % altchars, b'', encoded_bytes)

    # 2. Calculate missing padding:
    missing_padding = len(encoded_bytes) % 4

    # 3. Add padding if needed:
    if missing_padding:
        encoded_bytes += b'=' * (4 - missing_padding)

    # 4. Decode, handling potential errors
    try:
        return base64.b64decode(encoded_bytes, altchars=altchars)
    except base64.binascii.Error as e:
        print(f"Decoding error: {e}")
        return None  # Or raise the exception, depending on your needs

# Example of URL-safe Base64 (using '-' and '_')
urlsafe_encoded = b'SGVsbG8gV29ybGQh'  # "Hello World!" encoded
decoded_bytes = decode_base64(urlsafe_encoded, altchars=b'-_') # Use the function
print(decoded_bytes) # No output, because this example already have correct padding.

# Example of incorrect URL-safe
urlsafe_encoded_missing = b'SGVsbG8gV29ybGQ' # Last char removed
decoded_bytes = decode_base64(urlsafe_encoded_missing, altchars=b'-_') # Correct decoding
print(decoded_bytes) # Output: b'Hello World'

• Crucially, we call decode_base64 with altchars=b'-_'. This tells base64.b64decode to expect the URL-safe alphabet. If you don't provide this, it will use the standard Base64 alphabet and likely fail.
• The decode_base64 function will calculate how many padding characters = are needed, and will correctly decode the string.

Decoding Base64 Image Strings (Removing Prefixes)

from io import BytesIO
import base64
from PIL import Image

data = 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg=='

try:
   im = Image.open(BytesIO(base64.b64decode(data.split(',')[1])))
   im.save("my-image.png") # Save the image to verify it
except Exception as e:
    print(f"An error occurred: {e}")
# my-image.png is created.

• data.split(',')[1]: Splits the string at the comma and keeps the second part (index 1).
• You have to install the Pillow package to run the code: pip install Pillow.