A guard refused the call: no --pilot, a path outside the fence or on a protected path, a root flag that doesn’t match the pilot, a live-config check (details.field such as live.kitRoot, live.kitCommit, live.approval, live.home), an operation not allowed, or a command not available in live mode.
Read details.field and details.reason. Fix the cause, never the fence. For live mode see Live mode troubleshooting.
DEVTWIN_PATH_UNSAFE
A path is not canonical, goes through a symlink, has unsafe permissions, or is a repository that Git filters could touch. Also: private roots inside a Git worktree, or ~/.devtwin not private.
Use the real path (pwd -P, realpath). Check folder modes are 0700.
DEVTWIN_PATH_ESCAPE
A relative path tries to leave its root, or an output path is outside the bound worktree.
Use a plain relative path with no ...
DEVTWIN_INVALID_ID
A scope, project, request, record or actor ID is malformed.
See the ID formats in the CLI reference. A project ID must start with <scope>..
DEVTWIN_INVALID_INPUT
A value is invalid: unknown kind or status, bad source reference, malformed JSON input, bad profile field, unknown placeholder, reserved skill name.
An apply is missing --plan-fingerprint, or a record apply is missing --request-id.
Preview first, then pass the fingerprint (or request ID).
DEVTWIN_PLAN_MISMATCH
The fingerprint does not match the plan built now: flags differ, or sources or state changed since preview. For onboarding, the request ID may already have been applied with another plan.
Preview again with the same flags and review the new fingerprint.
DEVTWIN_STALE_VERSION
Something you based the change on moved: a superseded record’s hash (Target changed), the registry generation, your profile since preview, an approval or validation receipt, or a file during apply.
Re-read the current state, preview again, and approve the new plan.
DEVTWIN_APPROVAL_REQUIRED
An approval is missing or doesn’t match: confirmed without --reviewer, a stack check that differs from the stored approval, a non-canonical approval response, or hub records that aren’t confirmed.
Provide the missing approval, or re-approve the current plan. For the stack watch, run stack plan and stack approve again.
DEVTWIN_CONFLICT
A request ID was reused with different inputs, init or scope add differs from what exists, a live config already exists, or an onboarding plan has a blocking conflict.
Use a fresh request ID, or review what already exists. For an interrupted onboarding, follow the remedy: re-run project onboard with a new --request-id.
The worktree or project is not onboarded in that scope. details.reason is not-bound-in-scope or worktree-not-confirmed; details.remedy gives the command.
Text looks like a credential (details.types, such as credential-assignment), or a hub proposal names the scope, project, paths or hosts.
Remove the secret. Never store credentials in records, profiles or drafts.
DEVTWIN_ISOLATION
Text that leaves a scope names another scope: its ID, display name, a project ID, a bound root path or a remote host, as a whole word. A lesson for your personal store is checked against every scope.
Make the lesson general: drop client, repository, account and host names.
DEVTWIN_HANDOFF_UNSAFE
Selected record text can’t go into a portable packet: URLs, absolute or home paths, control characters, malformed metadata.
Select different records, or supersede the record with portable text.
DEVTWIN_POLICY_UNAVAILABLE
A required scope policy could not be read while building a brief.
Restore the policy file in the hub, or make the policy optional.
A size or count cap was hit: record body (32 KiB), profile (4 KiB), required policies over the brief budget, handoff packet (32 KiB, 12 records), too many sources, Git output over 16 MiB, more than 16 remotes, staged package caps. Also: a fourth lesson proposal in one session, a lesson too long for the owner dialog, or a hub with more than 5000 note files.
Shorten or split the input. Caps are fixed. Don’t change the session ID to get past the proposal cap.
The owner dialog was denied or dismissed, or there is no desktop session to show it (also in an SSH session). Nothing was written.
Run the command yourself in a desktop session, and click Approve only for text you reviewed.
DEVTWIN_UNAVAILABLE
setup apply named a step that is not available yet.
Run setup status to see which steps are available.
DEVTWIN_STALE_VERSION (lessons)
On lesson accept of a replacement: another replacement reached the hub first (already-superseded). On published delete: the file on the hub changed since the preview.
Run hub sync, then review what is now on the hub. The proposal stays pending.
DEVTWIN_CONFLICT (lessons)
On lesson supersede-propose: the lesson was removed by its author or is already superseded. On hub join: the scope already has a hub, or another scope joined this hub.
Another devtwin command holds a lock, or the lock owner is still running.
Wait for it. If nothing is running, preview locks release. Never delete the lock by hand.
DEVTWIN_RECOVERY_REQUIRED
An earlier operation stopped part way, or stored state is incomplete (binding, manifest, journal). New applies are blocked.
For skill installs, run agents recover. Otherwise read details.remedy, keep the files, and stop.
DEVTWIN_INTEGRITY
Stored data failed a check: a record bundle doesn’t match its hashes or ID, a staged file changed, a seeded template file was edited. handoff export names corrupt record IDs in details.records.
Don’t edit, rename or delete the files. Run doctor (its bundles check counts corrupt records) and review the files under dataRoot.
DEVTWIN_SOURCE_CHANGED
A file changed while devtwin was reading it, or between check and write.
Let the file settle and retry.
DEVTWIN_ROLLBACK_MISMATCH
agents rollback-check found devtwin-* entries that differ from the pre-install inventory.
Review the listed changes. Run the check right after uninstalling.
DEVTWIN_STORAGE_ERROR
A filesystem operation devtwin needs, such as hard links, failed.
DEVTWIN_AUTH_UNVERIFIED, DEVTWIN_AUTH_MISMATCH and DEVTWIN_APPROVAL_INVALID exist in the internal auth library, which has no CLI command yet. They will surface with identity routing.
DEVTWIN_INTERNAL wraps an unexpected exception; the message is the underlying error, truncated. It is a bug. Report it with a synthetic reproduction; see Contributing.
One known case: agents status with a disposable pilot and no --home currently fails with DEVTWIN_INTERNAL. Pass --home.
