# wrangler kv key put failed: key too long

## TL;DR

The KV key exceeds the 512-byte limit. Shorten it: hash the long suffix, restructure the key scheme, or move metadata out of the key. Keys are addresses, not storage.

```text
wrangler kv:key put failed: key too long
```

## Steps

1. Measure the key: it exceeds 512 bytes.
   Expected: The overage is confirmed.

2. Redesign the key: keep a short prefix and hash the long variable part.
   Expected: Keys fit the limit.

3. Update all readers and writers to the new scheme.
   Expected: The scheme is consistent.

4. Re-put the values under the new keys; delete the old long-key attempts if any landed.
   Expected: The data is reachable.

5. Add a key-length assertion in the KV client wrapper.
   Expected: Overlong keys fail fast locally.

## When to use

- KV puts fail with key too long
- keys embed URLs or long IDs
- the key scheme grew organically

## When not to use

- the key is short (check for invisible characters or encoding)
- the error is on value size (different limit)
- using a different store (limits differ)

## Tool compatibility

- wrangler
- Cloudflare KV (512-byte key limit)

## Variant phrasings

- "kv key too long"
- "wrangler kv put key length"
- "cloudflare kv 512 byte key"

## Why it happens

KV keys are limited to 512 bytes, and key schemes that embed URLs, tokens, or compound IDs blow past it. The key is an address; anything that does not help addressing belongs in the value. Hashing the variable part keeps uniqueness without the length.

## Edge cases

- the limit is bytes, not characters; multibyte UTF-8 counts more
- hashed keys are opaque; keep a separate index if humans need to browse
- the assertion belongs in the shared client so every caller benefits

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_p9NasGCOid5_921g9tMZGg