workerd TypeError: Durable Object ID from string is invalid

Fix Durable Object ID from string is invalid

TL;DR

idFromString only accepts IDs that were produced by idFromName or id.toString() - 64 hex characters. If you are passing a human-readable name like "user-123", use idFromName instead. Reserve idFromString for round-tripping strings that came from id.toString().

Verbatim error

workerd TypeError: Durable Object ID from string is invalid

Steps

1. Find the failing call by searching for idFromString in your code. Expected: you locate the exact line.
2. Check what string you pass: if it is a name such as "user-123", replace the call with env.MY_DO.idFromName("user-123"). Expected: you get a valid ID object with no error.
3. If you stored the ID string earlier, confirm it came from id.toString() (64 lowercase hex characters). Expected: the stored value matches that format.
4. Keep the pair consistent going forward: idFromName for names, idFromString only for stored toString() values. Expected: both code paths work.
5. Test the round-trip: create via idFromName, call toString(), then idFromString() on the result. Expected: the same ID, no error.

Use this when

• A Worker throws "Durable Object ID from string is invalid"
• You are migrating from name-based IDs to stored ID strings
• You parse DO IDs from URLs, KV, or request bodies

Not for this skill when

• Names collide across namespaces (names are unique per class plus namespace, which is by design)
• The DO class binding itself is missing from wrangler.toml
• The error is a storage error inside the Durable Object

Variant phrasings

• idFromString throws invalid
• durable object id invalid hex
• how to get durable object by name
• DO idFromString malformed

Why it happens

Durable Object IDs are 256-bit values rendered as 64 hex characters. idFromString validates strictly and rejects anything else, while idFromName hashes an arbitrary name into a valid ID. Mixing up the two APIs - passing a name to idFromString - is the usual bug.

Edge cases

• toString() output is lowercase hex; uppercase or truncated strings are rejected.
• IDs are unique per class, not globally; include the class name in any storage key you build from them.
• Never trust user-supplied ID strings without validating the 64-hex format first.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstw5lqYtfcwajkCuatzO-nQ