If your project was created a while ago and you've been unable to build or deploy — or if builds have become unreliable — your project may be on an older format that needs migration. Caffeine now handles this automatically when you open an older project.
What happens when you open an older project
When you open a project that was built before the current platform version, Caffeine runs an automatic migration before your first build. Depending on how old the project is, this may include one or more of the following:
Project structure update. Older projects stored files in a different directory layout. The migration restructures them to match the current format, adds the current project template files (mops.toml, package.json, caffeine.toml), and removes files that are no longer needed.
Component upgrade. Older projects used vendored source files for features like authorization, file storage, Stripe payments, and email. These are now published packages — the vendored files are removed and replaced by standard package imports. For example, code that previously imported from a local authorization/ directory now imports from the caffeineai-authorization package.
Motoko data structure migration. The Motoko standard library was updated from mo:base to mo:core. The data structures in each have different internal representations — you can't simply change the import statements or the app will break on upgrade. When the migration detects mo:base usage, it instructs the AI to create migration files that safely convert your data structures before any other work begins. This includes:
- A helper module with conversion functions for maps, sets, and lists
- A migration module that defines the old and new data shapes and maps between them
- An update to your main backend file that wires in the migration
The migration runs as the AI's first task — you may see it creating these files before it addresses your actual request.
What you'll notice
- New template files appear —
caffeine.toml, updatedmops.toml, updatedpackage.json. These are part of the current project format. - Vendored directories disappear — folders like
src/backend/authorization/,src/backend/stripe/, and similar are removed and replaced by package imports. - Import paths change — frontend code that imported from local hook files now imports from
@caffeineai/core-infrastructureor@caffeineai/object-storage. Backend code that imported from local directories now imports fromcaffeineai-*packages. - Migration files may appear — if your project uses older Motoko data structures, you'll see
BaseToCore.moandmigration.mofiles created in the backend directory. - An
.old/directory appears — this is a read-only snapshot of your project before the migration, used by the AI to verify that the upgrade is compatible with your existing data. You can't edit it and it doesn't affect your app.
What to do
In most cases, nothing. The migration runs automatically and the AI handles the details. After the migration completes, you can continue building as normal — send your prompt and the AI will work with the migrated project.
If the migration creates Motoko data structure files, the AI will verify the upgrade is safe by compiling both the old and new versions and checking compatibility. If something doesn't compile, it will attempt to fix the issue automatically.
When migration doesn't work
There are a few situations where automatic migration may not fully resolve the issue:
Customized vendored files. If you manually modified the vendored source files (for example, changed the authorization module's behavior), those customizations are lost when the directory is replaced by the published package. You would need to re-apply customizations on top of the new package.
Projects using preupgrade/postupgrade hooks. The current Motoko toolchain uses a newer persistence model that is incompatible with the old preupgrade/postupgrade system functions. Projects that rely on these hooks need manual refactoring that goes beyond what the automatic migration handles.
Very old projects that won't compile. The migration needs to compile the old backend code one final time to extract its data structure signature for compatibility checking. If the old code can't compile with the current toolchain, this step is skipped and the upgrade can't be verified automatically.
If your project is stuck after the migration runs, contact support with your project ID and a description of what happened.
Frequently asked questions
Will I lose my live app's data?
No. The migration is designed to preserve your data. The Motoko data structure migration specifically converts your existing data into the new format — it doesn't delete or overwrite it. The AI also verifies compatibility before deploying.
Do I need to do anything to trigger the migration?
No. Just open your project and send a message. The migration runs automatically if needed.
Can I opt out of the migration?
No. The migration is required to use the current build system. Older project formats are no longer supported by the AI agents.
My project was stuck for weeks. Will this fix it?
In many cases, yes. The most common reason projects get stuck is incompatibility between older project formats or data structures and the current toolchain. The automatic migration is designed to resolve exactly this. If your project is still stuck after the migration, contact support.
How do I know if my project was migrated?
You'll see new template files (caffeine.toml, updated mops.toml) in your project. If Motoko data structures were migrated, you'll also see BaseToCore.mo and migration.mo files in the backend directory.