## TL;DR

Base64 comes in flavors: standard versus URL-safe alphabets, with or without padding. Normalize the input (translate the alphabet, restore padding) before decoding, and fail clearly on invalid input.

## Error

```text
agent's base64 decoder broke on padded secret values error
```

## Steps

1. Inspect the failing value's alphabet: URL-safe uses different characters for two positions. Expected: the flavor identified.
2. Normalize: translate URL-safe characters to standard, then pad to a multiple of four. Expected: decodable input.
3. Decode with strict validation. Expected: bytes or a clear error.
4. On invalid input, report which value failed rather than crashing. Expected: diagnosable failure.
5. Document which flavor the pipeline produces so encoders and decoders agree. Expected: no mismatch.

## When to use

- Base64 decode failures on secret values.
- Interop between systems with different flavors.

## When not to use

- Input that is not base64 at all (fix the producer).
- Encrypted blobs that only look like base64 (decrypt first).

## Tool compatibility

- Standard base64 libraries; URL-safe variants.

## Variant phrasings

### base64 padding error

Restore padding.

### invalid base64 on secret

Check the alphabet.

## Why it happens

Producers strip padding and use URL-safe alphabets for transport; consumers assuming standard padded input break.

## Edge cases

- Do not guess: detect the flavor from the characters present.
- Decoded secrets are sensitive; handle the bytes carefully.
- Some values are base64 of base64; decode once unless documented.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_B30-dcS0ZxV_hCEcwo3kRg