{"record":{"id":"fbe8fed4ae438946","repo":"lcobucci/jwt","slug":"error-while-decoding-from-base64url-invalid-base64","errorCode":null,"errorMessage":"Error while decoding from Base64Url, invalid base64 characters detected","messagePattern":"Error while decoding from Base64Url, invalid base64 characters detected","errorType":"exception","errorClass":"Lcobucci\\JWT\\Encoding\\CannotDecodeContent","httpStatus":null,"severity":"error","filePath":"src/SodiumBase64Polyfill.php","lineNumber":72,"sourceCode":"\n        return $encoded;\n    }\n\n    /**\n     * @return ($encoded is non-empty-string ? non-empty-string : string)\n     *\n     * @throws CannotDecodeContent\n     */\n    public static function base642bin(string $encoded, int $variant): string\n    {\n        if (! function_exists('sodium_base642bin')) {\n            return self::base642binFallback($encoded, $variant); // @codeCoverageIgnore\n        }\n\n        try {\n            return sodium_base642bin($encoded, $variant, '');\n        } catch (SodiumException) {\n            throw CannotDecodeContent::invalidBase64String();\n        }\n    }\n\n    /**\n     * @return ($encoded is non-empty-string ? non-empty-string : string)\n     *\n     * @throws CannotDecodeContent\n     */\n    public static function base642binFallback(string $encoded, int $variant): string\n    {\n        if (\n            $variant === self::SODIUM_BASE64_VARIANT_URLSAFE\n            || $variant === self::SODIUM_BASE64_VARIANT_URLSAFE_NO_PADDING\n        ) {\n            $encoded = strtr($encoded, '-_', '+/');\n        }\n\n        $decoded = base64_decode($encoded, true);","sourceCodeStart":54,"sourceCodeEnd":90,"githubUrl":"https://github.com/lcobucci/jwt/blob/375813049c24c7111bda8b6884c57b071ceb2fe7/src/SodiumBase64Polyfill.php#L54-L90","documentation":"This error wraps a low-level failure when decoding a Base64Url-encoded string in SodiumBase64Polyfill::base642bin. When the native sodium_base642bin() throws SodiumException (invalid base64 characters), the polyfill converts it into CannotDecodeContent::invalidBase64String(). It means the input string is not valid Base64Url data — usually it contains '+', '/', '=' or other non-URL-safe characters, or is corrupted/truncated.","triggerScenarios":"Calling base64UrlDecode() or base642bin() on a string that contains standard-Base64 characters ('+','/') instead of Base64Url ('-','_'), padding '=' characters, whitespace, or any corrupted bytes. Also raised indirectly by parser signature decoding (signatureValidationWithLocalFileKeyReferenceWillOperateWithKeyContents, initializeKey call sites) when a JWT segment is not valid Base64Url.","commonSituations":"Passing a regular base64-encoded token into a Base64Url decoder; copying a JWT from a source that replaced '-'/'_' with '+'/'/'; appending '=' padding that Base64Url forbids; decoding a signed payload with a truncated or tampered segment.","solutions":["Inspect the input string for illegal characters and strip/normalize '=' padding and whitespace before decoding","Convert standard base64 to base64url first: strtr($value, '+/', '-_') and rtrim($value, '=')","Verify the JWT is complete and was not truncated or mangled during transport/storage","If you control the encoder, encode with SodiumBase64Polyfill::bin2base64($data, SODIUM_BASE64_VARIANT_URLSAFE_NO_PADDING)","Wrap the decode in try-catch for CannotDecodeContent and surface a clear 'invalid token encoding' message to the caller"],"exampleFix":"// before\n$decoded = SodiumBase64Polyfill::base642bin($value, SODIUM_BASE64_VARIANT_URLSAFE);\n// after\n$value = rtrim(strtr($value, '+/', '-_'), '=');\n$decoded = SodiumBase64Polyfill::base642bin($value, SODIUM_BASE64_VARIANT_URLSAFE_NO_PADDING);","handlingStrategy":"try-catch","validationCode":"if (!preg_match('/^[A-Za-z0-9_-]*$/', $input)) { throw new InvalidArgumentException('Invalid base64url'); }","typeGuard":"function isValidBase64Url(string $s): bool { return preg_match('/^[A-Za-z0-9_-]*$/', $s) === 1; }","tryCatchPattern":"try { $decoded = SodiumBase64Polyfill::base64UrlDecode($input); } catch (Lcobucci\\JWT\\Encoding\\CannotDecodeContent $e) { return error_400('Malformed token encoding'); }","preventionTips":["Normalize input to base64url (strtr + rtrim '='), before decoding","Regex-validate token segments before decode","Always catch CannotDecodeContent at the boundary (middleware) rather than letting it 500"],"tags":["base64","encoding","jwt","php"],"backgroundTag":"invalid-argument-format","analyzedSha":"375813049c24c7111bda8b6884c57b071ceb2fe7","analyzedAt":"2026-09-14T11:12:28.004Z","contentChangedAt":"2026-09-14T11:12:28.004Z","schemaVersion":2},"datasetVersion":"2026-09-16T09:17:16.951Z"}