paascloud/paascloud-master · error · BadCredentialsException

Failed to decode basic authentication token

Error message

Failed to decode basic authentication token

What it means

RequestUtil.extractAndDecodeHeader throws BadCredentialsException("Failed to decode basic authentication token") when the Base64 portion of the Basic auth header cannot be decoded. It indicates the credential payload after "Basic " is not valid Base64, so authentication cannot proceed.

Solutions

1. Encode credentials properly: Base64(username + ":" + password) and send as "Basic " + encoded.
2. Check that the scheme prefix is exactly "Basic " (6 chars) so the substring taken is really the Base64 part.
3. On the client, use a standard helper (e.g. btoa/HttpHeaders) rather than manual concatenation.

Example fix

// before
header = "Basic admin:secret"; // raw, not Base64
// after
String encoded = Base64.getEncoder().encodeToString("admin:secret".getBytes(StandardCharsets.UTF_8));
header = "Basic " + encoded;

String payload = header.startsWith("Basic ") ? header.substring(6) : null;
if (payload == null || !Base64.getDecoder().decode(payload.getBytes(StandardCharsets.UTF_8)).hasRemaining()) {
    throw new BadCredentialsException("Authorization header payload is not valid Base64");
}

try {
    String[] creds = RequestUtil.extractAndDecodeHeader(header);
} catch (BadCredentialsException e) {
    response.sendError(HttpServletResponse.SC_BAD_REQUEST, e.getMessage());
}

When it happens

Trigger: Calling extractAndDecodeHeader with a header like "Basic !!!not-base64!!!" — the substring after index 6 fails Base64.decode and Base64.decode throws IllegalArgumentException.

Common situations: Clients manually building the header with an unencoded username:password string instead of Base64, double-encoding mistakes, or a frontend sending the raw token without the scheme handled correctly.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

• Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.
• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• Invalid basic authentication token
• UAC10011040
• UAC10011041
• UAC10011039
• Authentication method not supported:

AI-assisted analysis of paascloud/paascloud-master@781281a950 (2026-09-10). Data as JSON: /api/errors/ab207c9ff616e5be. Report an issue: GitHub.

Appendix: source

Thrown at paascloud-common/paascloud-common-core/src/main/java/com/paascloud/core/utils/RequestUtil.java:141

	 * @return the auth header
	 */
	public static String getAuthHeader(HttpServletRequest request) {

		String authHeader = request.getHeader(HttpHeaders.AUTHORIZATION);
		if (org.apache.commons.lang.StringUtils.isEmpty(authHeader)) {
			throw new BusinessException(ErrorCodeEnum.UAC10011040);
		}
		return authHeader;
	}

	public static String[] extractAndDecodeHeader(String header) throws IOException {

		byte[] base64Token = header.substring(6).getBytes("UTF-8");
		byte[] decoded;
		try {
			decoded = Base64.decode(base64Token);
		} catch (IllegalArgumentException e) {
			throw new BadCredentialsException("Failed to decode basic authentication token");
		}

		String token = new String(decoded, "UTF-8");

		int delim = token.indexOf(GlobalConstant.Symbol.MH);

		if (delim == -1) {
			throw new BadCredentialsException("Invalid basic authentication token");
		}
		return new String[]{token.substring(0, delim), token.substring(delim + 1)};
	}
}

View on GitHub (pinned to 781281a950)