AWS
MalformedQueryString - Malformed Query String
Hitting a **MalformedQueryString** error means your AWS API request has invalid query string syntax—special characters aren't URL-encoded, parameters are duplicated, or the query format violates AWS API requirements. This client-side error (4xx) happens when AWS parses query parameters. Most common when building S3 presigned URLs or API Gateway requests manually, but also appears when query parameters have unencoded special characters, duplicate parameter names exist, or query string syntax is invalid.
#Common Causes
- →Identity: IAM policy query string restrictions. Service Control Policy (SCP) blocks certain query parameters.
- →Network: VPC endpoint query string validation. API Gateway query parameter limits.
- →Limits: Query string too long. Invalid query format. Unencoded special characters (&, =, +, space). Duplicate parameter names. Missing required parameters.
✓Solutions
- 1Step 1: Diagnose - Check exact error message: AWS usually specifies which parameter is malformed. Review query string for special characters. Check for duplicate parameters.
- 2Step 2: Diagnose - Validate query string format: Query should be key=value&key2=value2. No unencoded spaces, &, =, or +. Use URL encoding: space=%20, &=%26, ==%3D.
- 3Step 3: Diagnose - Check parameter encoding: Use URL encoding for special chars. Spaces must be %20 or +. & must be %26. = must be %3D. Test with: echo "param=value with space" | sed 's/ /%20/g'.
- 4Step 4: Fix - Use AWS SDK parameter objects: Instead of building query strings manually, use SDK: aws s3api list-objects-v2 --bucket BUCKET --prefix PREFIX. SDK handles encoding automatically.
- 5Step 5: Fix - Encode query parameters properly: Use URL encoding: curl "https://s3.amazonaws.com/bucket?prefix=folder%2Fsubfolder&max-keys=100". Or use AWS CLI which handles encoding: aws s3api list-objects-v2 --bucket bucket --prefix "folder/subfolder" --max-keys 100.
</>Code Examples
Use AWS CLI to Avoid Query String Issues
1#!/bin/bash
2# AWS CLI handles encoding automatically - use it instead of manual query strings
3BUCKET_NAME="my-bucket"
4PREFIX="folder/subfolder"
5
6echo "=== Using AWS CLI (handles encoding) ==="
7aws s3api list-objects-v2 \
8 --bucket ${BUCKET_NAME} \
9 --prefix "${PREFIX}" \
10 --max-keys 100
11
12# This is better than manually building:
13# BAD: https://s3.amazonaws.com/bucket?prefix=folder/subfolder
14# GOOD: Use AWS CLI or SDK which encodes automaticallyURL Encode Query Parameters Manually
1#!/bin/bash
2# Function to URL encode a string
3urlencode() {
4 local string="${1}"
5 local strlen=${#string}
6 local encoded=""
7
8 for (( pos=0 ; pos<strlen ; pos++ )); do
9 c=${string:$pos:1}
10 case "$c" in
11 [-_.~a-zA-Z0-9] ) encoded+="${c}" ;;
12 " " ) encoded+="%20" ;;
13 "&" ) encoded+="%26" ;;
14 "=" ) encoded+="%3D" ;;
15 "+" ) encoded+="%2B" ;;
16 * ) printf -v encoded "%%%02x" "'$c" ;;
17 esac
18 done
19 echo "${encoded}"
20}
21
22# Example: Encode a prefix with special characters
23PREFIX="folder/subfolder with spaces"
24ENCODED_PREFIX=$(urlencode "${PREFIX}")
25echo "Original: ${PREFIX}"
26echo "Encoded: ${ENCODED_PREFIX}"
27
28# Build query string properly
29BUCKET="my-bucket"
30QUERY_STRING="prefix=${ENCODED_PREFIX}&max-keys=100"
31echo "\nQuery string: ${QUERY_STRING}"Validate Query String Format
1#!/bin/bash
2# Check for common query string issues
3QUERY_STRING="prefix=folder/sub&max-keys=100&duplicate=1&duplicate=2"
4
5echo "=== Checking Query String: ${QUERY_STRING} ==="
6
7# Check for unencoded special characters
8if [[ ${QUERY_STRING} =~ [^a-zA-Z0-9%&=._-] ]]; then
9 echo "✗ Contains unencoded special characters"
10 echo " Encode spaces, &, =, and other special chars"
11else
12 echo "✓ No obvious encoding issues"
13fi
14
15# Check for duplicate parameters
16echo "\n=== Checking for Duplicate Parameters ==="
17PARAMS=$(echo ${QUERY_STRING} | tr '&' '\n' | cut -d'=' -f1)
18DUPLICATES=$(echo "${PARAMS}" | sort | uniq -d)
19if [ ! -z "${DUPLICATES}" ]; then
20 echo "✗ Duplicate parameters found: ${DUPLICATES}"
21 echo " Remove duplicates from query string"
22else
23 echo "✓ No duplicate parameters"
24fi
25
26# Best practice: Use AWS CLI instead
27echo "\n=== Best Practice: Use AWS CLI ==="
28echo "Instead of building query strings manually, use:"
29echo "aws s3api list-objects-v2 --bucket BUCKET --prefix PREFIX --max-keys 100"↗Related Errors
Provider Information
This error code is specific to AWS services. For more information, refer to the official AWS documentation.