Syncing & recovery

Local app development revolves around syncing: the CLI rebuilds your manifest and the server applies only the difference between it and the metadata already in your workspace. This page covers which command to reach for, how to read what a sync changed, and what to do — in order — when local state looks inconsistent.

Which command, when

For day-to-day local iteration you almost always want yarn twenty dev. Deploying and publishing are for shipping releases, not for the local loop.

You want to…	Command	Notes
Iterate locally with live sync	`yarn twenty dev`	Watches your files and syncs on every change.
Sync once and exit (CI, scripts, hooks)	`yarn twenty apply`	One build + sync, then exits. Add `--force` to skip the destructive-change confirmation.
Preview changes without applying them	`yarn twenty plan`	Computes and prints the diff; writes nothing.
Sync without deleting anything	`yarn twenty apply --no-delete`	Creates and updates only: entities that exist in the workspace but not in your source are left alone. Also accepted by `plan` and `dev`.
Remove the app from the workspace	`yarn twenty app:uninstall`	Add `--yes` to skip the prompt.
Ship a tarball to a server	`yarn twenty app:publish --private`	Requires a strictly higher `package.json` version — see Publishing.
Publish to the marketplace (npm)	`yarn twenty app:publish`	—
Install / upgrade a deployed version	`yarn twenty app:install`	Installs the version currently deployed.
Wipe the local server and start clean	`yarn twenty docker:reset`	Deletes all local data — last resort.

yarn twenty dev --once and yarn twenty dev --once --dry-run still work as deprecated aliases for yarn twenty apply and yarn twenty plan.

Local sync does not need a version bump

The strictly-increasing version rule (VERSION_ALREADY_EXISTS on deploy, APP_ALREADY_INSTALLED / CANNOT_DOWNGRADE_APPLICATION on install) applies to app:publish / app:install — the release path. yarn twenty dev syncs your manifest in place and never requires a version change, so you don’t need to touch package.json to iterate. If you find yourself bumping the version to test a local change, you’re using the release path when you want the dev loop.

Reading the sync output

Every sync prints the metadata changes it applied (or would apply, with plan), Terraform-style — one block per entity with its attributes, then a summary line:

  # objectMetadata "rocket" will be created
  + icon          = "IconRocket"
  + labelSingular = "Rocket"
  + ...

  # fieldMetadata "launchedAt" will be updated
  ~ isNullable = false -> true

Plan: 2 to add, 1 to change, 1 to destroy.

✓ Synced My App (4 files)

This is your first diagnostic: it tells you exactly which objects, fields, and layouts changed, so you can confirm a sync did what you expected before checking the UI. Destructive changes (to destroy) are listed with what they drop (e.g. objectMetadata "auditNote" — drops the table and all its rows) and require interactive confirmation, or --force in scripts. A sync deletes every entity your app owns that your source no longer declares. When a plan contains destroys it says so and points at --no-delete, which makes the sync additive: creates and updates are applied, nothing missing from your source is deleted. Use it when your source is intentionally partial, for example while adopting an app that was built in the UI. When a sync fails on a single entity, the error names the offending entity and its universalIdentifier, for example:

Migration action 'create' for 'fieldMetadata' (universalIdentifier: 2020...4337) failed

Use that identifier to find the entity in your manifest (and, if needed, in the workspace) instead of guessing which one conflicts.

Previewing changes (plan)

yarn twenty plan builds your manifest, asks the server for the migration plan, and prints it — without applying anything. It’s the safe way to answer “what would this sync change?” before committing to it.

yarn twenty plan

Building manifest...
Computing metadata plan (read-only, nothing will be applied)...

  # fieldMetadata "crewCapacity" will be created
  + ...

Plan: 1 to add, 1 to change, 0 to destroy.

✓ Plan complete for My App — no changes were applied

A plan:

Writes nothing — no metadata migration, no application record update, no default role/tab changes, and no API client generation.
Returns the same diff a real sync would apply, so you can review created/updated/deleted entities up front.
Is useful before a risky change, when reviewing an AI-generated change, or in a script that should fail if an unexpected change is about to land.

A plan only previews metadata changes. It also works for an app that was never synced: the server evaluates the manifest against an empty application, so the plan lists everything your source would create.

Recovery ladder

When local metadata looks wrong, escalate in this order and stop as soon as you’re unblocked. Each step is more disruptive than the last.

Re-sync. Run yarn twenty apply again. Syncs are idempotent — re-running a clean manifest is safe and often resolves a transient hiccup.
Preview the plan. Run yarn twenty plan to see exactly what the next sync intends to change, without applying it.
Read the named error. If a sync fails, note the metadata type and universalIdentifier in the message (see above) and locate that entity in your manifest. A conflict usually points to a duplicated or re-used identifier.
Uninstall and reinstall. yarn twenty app:uninstall, then sync again (yarn twenty dev). This rebuilds the app’s metadata from a clean slate while keeping the rest of your workspace intact.
Full reset (last resort). yarn twenty docker:reset, then re-seed and re-sync.

yarn twenty docker:reset deletes all data in your local instance — every workspace, record, and app. Only use it once the earlier steps have failed.

Hit a metadata error? Please open an issue and include the failing migration message (with its metadata type and universalIdentifier), the Metadata changes output from the sync, and the commands you ran.

Avoid concurrent syncs on one workspace

Syncing applies metadata migrations. Running several sync, deploy, or install operations against the same workspace at the same time — for example, multiple terminals or AI agents iterating in parallel — can interleave those migrations and leave metadata in a partially-applied state. The server serializes syncs per workspace to prevent this, but you should still funnel sensitive metadata operations through a single process rather than firing them concurrently. If you orchestrate development with multiple agents, route their sync/deploy/install calls through one queue so only one runs at a time.

Telling failures apart

When something goes wrong, the metadata diff and named errors let you place the failure:

Manifest build error — the CLI fails before syncing (MANIFEST_BUILD_FAILED, TYPECHECK_FAILED); fix your app source.
Registration ownership error — the sync is refused because the app’s universalIdentifier belongs to another workspace, or to no workspace at all; see Registration ownership.
Sync / migration error — the build succeeds but applying the diff fails, naming the entity and universalIdentifier; fix the conflicting metadata.
Dependencies size error — the sync or install fails because the app’s production dependencies are too large to install as a runtime layer (LOGIC_FUNCTION_DEPENDENCIES_SIZE_EXCEEDED); move packages your logic functions do not import at runtime (UI libraries, dev tooling) to devDependencies.
App code runtime error — the sync succeeds but your logic functions or components misbehave at runtime; check function logs.
Local instance state — none of the above and the workspace still looks wrong; work down the recovery ladder.

Overview

Apps

API

Self-Host

Contribute

Which command, when

Local sync does not need a version bump

Reading the sync output

Previewing changes (plan)

Recovery ladder

Avoid concurrent syncs on one workspace

Telling failures apart

​Which command, when

​Local sync does not need a version bump

​Reading the sync output

​Previewing changes (plan)

​Recovery ladder

​Avoid concurrent syncs on one workspace

​Telling failures apart

Which command, when

Local sync does not need a version bump

Reading the sync output

Previewing changes (plan)

Recovery ladder

Avoid concurrent syncs on one workspace

Telling failures apart