Garbled binary over Upstash REST: use the Upstash-Encoding base64 header

TL;DR: Binary values come back with replacement characters over REST unless you request base64 encoding with the Upstash-Encoding header. Confirm Read the same key over the native protocol (redis-cli) or with responseEncoding enabled in the SDK. Fix Request base64 encoding: curl https://YOURRESTURL/get/mykey \ -H "your auth header \ -H "Upstash-Encoding: base64" The result field comes back base64-encoded; decode client side.

The fix

Diagnosing garbled binary values over Upstash REST

Symptom

Values containing binary data come back with replacement characters (U+FFFD) or fail JSON parsing. Text values are fine.

Cause

REST responses are JSON. Bytes that are not valid UTF-8 cannot survive JSON transport, so the API substitutes the replacement character. Your stored bytes are intact; the read path mangled them.

Confirm

Read the same key over the native protocol (redis-cli) or with responseEncoding enabled in the SDK. If the bytes are correct there, the REST text transport is the problem.

Fix

Request base64 encoding:

curl https://YOURRESTURL/get/mykey \ -H "your auth header \ -H "Upstash-Encoding: base64"

The result field comes back base64-encoded; decode client side. In @upstash/redis this is the default behavior, which is why SDK reads work while raw curl reads look garbled.

Do not combine this header with Upstash-Response-Format: resp2. That combination is a 400.

Verify

Round trip known binary bytes and compare byte for byte after decoding. Exact match means the transport is clean.

When to use this

• This covers exactly what the title says: Garbled binary over Upstash REST.
• You are setting this up for the first time, or auditing an existing setup.
• You want the key gotchas in one place before you start.

When not to use this

• You are doing a different workflow with Garbled; these steps are specific to the title above.
• You need the full reference docs; this is the short path, not the manual.

Compatibility

• Not pinned to a specific version; follows current Garbled behavior.

Verified against Upstash REST API docs: invalid UTF-8 in responses is replaced with the U+FFFD replacement character; setting the Upstash-Encoding header to base64 returns all strings base64-encoded; base64 cannot be combined with resp2 format. Source: https://upstash.com/docs/redis/features/restapi