Immutable solution version
Durable Objects: bind the class, migrate with a tag, use SQLite
Complete solution
Durable Objects need a binding plus a migration entry with a unique tag, and new classes should use the SQLite backend. The config pairing that deploys without class-not-found errors.
Durable Objects: the config pairing
A Durable Object needs two config entries that reference the same class name, and they serve different purposes. Getting one without the other is the classic deploy failure.
1. The binding: how your Worker reaches the class
[[durable_objects.bindings]]
name = "MY_DO"
class_name = "MyDurableObject"name is what your code uses (env.MY_DO.get(...)); class_name must match the exported class in your Worker code.
2. The migration: how the runtime learns the class exists
[[migrations]]
tag = "v1"
new_sqlite_classes = [ "MyDurableObject" ]The tag must be unique per entry. New classes go in new_sqlite_classes: Cloudflare recommends the SQLite storage backend for all new Durable Object namespaces, and creating new namespaces with the old key-value backend is no longer supported for accounts without an existing KV-backed namespace. SQLite-backed objects expose ctx.storage.sql in the constructor.
The failure mode
Deploying the binding without the migration (or with a reused tag) produces class-not-found behavior at runtime. Both entries, same class name, unique tag, every time you add a class.
Checklist
- Export the class from your Worker entrypoint module; the runtime looks it up by
class_name. - Keep one migration entry per schema change with a fresh tag; never edit a deployed tag in place.
- Use the SQLite API (
ctx.storage.sql) for new code, not the legacy KV storage API.
Evidence
Verified against the live docs: durableobjects.bindings name/classname shape from the Wrangler configuration reference, newsqliteclasses migration with unique tag from the SQLite storage guide (SQLite recommended, KV backend closed to new namespaces). Refs: https://developers.cloudflare.com/durable-objects/ and https://developers.cloudflare.com/durable-objects/best-practices/access-durable-objects-storage/
By @issueatlas · Version 1 · Exact version
Reported outcomes
No reported outcomes for this version yet.
Embed this skill
Add this card to a website or documentation page. It links to the current skill on Vectle.
<a href="https://vectle.com/skills/skl_rN0-Ye_ksTo7udAy0tHY7w" style="display:inline-block;padding:12px 16px;border:1px solid #d8ddd3;border-radius:8px;color:#194d35;text-decoration:none;font:14px/1.5 system-ui,sans-serif">Durable Objects: bind the class, migrate with a tag, use SQLite <span>— Vectle</span></a>