Message: local_identity is not initialized / Failed to read key file: <path> / owner identity is not initialized / worker identity is not initialized / owner actor key not found / worker actor key not found

Cause: The identity has not been created, or the key file cannot be found.

Resolution:

Run starweft identity create
Verify that identity.actor_key_path in config.toml points to the correct path

Peer Errors (E_PEER_*)

E_PEER_LIMIT

Message: Peer limit reached: configured=<max> current=<count>

Cause: The number of registered peers has reached the p2p.max_peers limit.

Resolution:

Increase p2p.max_peers in config.toml
Remove unnecessary peers

Role Errors (E_ROLE_*)

E_ROLE_MISMATCH

Message: vision submit can only be run with the principal role / stop can only be run with the principal role / project approve can only be run with the owner or principal role / task approve can only be run with the owner or principal role

Cause: The role required by the command does not match the current node's role.

Resolution:

Run the command on a node with the correct role
Use starweft identity show to check the node's role

Project and Task Errors

E_PROJECT_NOT_FOUND

Message: Project not found / Principal actor not found

Cause: The specified project ID does not exist in the store, or the project's principal actor cannot be resolved.

Resolution:

Use starweft project list to verify the project ID
Confirm that the vision was submitted successfully

E_TASK_NOT_FOUND

Message: Task not found / Task does not belong to the project / Retry source task blueprint not found / Planner task blueprint not found / Root task does not belong to the project

Cause: The specified task ID does not exist in the store, or does not belong to the specified project.

Resolution:

Use starweft task list to verify the task ID
Confirm that the --project and --task combination is correct

E_VISION_NOT_FOUND

Message: Vision for the project not found

Cause: The vision record associated with the project cannot be found.

Resolution:

Confirm that the vision was submitted successfully

E_TASK_CANCELLED

Message: openclaw process cancelled

Cause: The OpenClaw subprocess was cancelled by a stop order.

Resolution:

No action is needed if the stop was intentional
If the stop was unintentional, check starweft events to review the stop order

Owner Resolution Errors

E_OWNER_UNRESOLVED

Message: Owner peer not found. Please specify --owner / Cannot uniquely determine the owner. Please specify --owner

Cause: No owner peer is registered, or there are multiple candidates and automatic resolution is not possible.

Resolution:

Specify explicitly with --owner <ACTOR_ID>
Use starweft peer list to check registered peers

Argument Errors (E_ARGUMENT)

E_ARGUMENT

Message: Various argument validation errors

Common messages:

Message	Resolution
`Specify either --project or --task-tree, not both`	Specify only one of the mutually exclusive flags
`Specify either --project or --task, not both`	Specify only one of the mutually exclusive flags
`--text and --file cannot be specified at the same time`	Use one or the other
`Either --text or --file is required`	Specify a text input
`Constraints must be in key=value format`	Specify as `--constraint key=value`
`--public-key and --public-key-file cannot be specified at the same time`	Use one or the other
`--repo must be in owner/repo format`	Specify in `owner/repo` format
`Specify either --issue or --pr, not both`	Specify only one of the mutually exclusive flags
`Specify exactly one of --vision / --project / --task / --stop`	Specify only one wait target
`--missing-only must be used with --dry-run`	Add `--dry-run`
`--approve cannot be specified with --dry-run`	Remove `--dry-run`
`Invalid RFC3339 timestamp`	Specify in RFC3339 format (e.g., 2026-01-01T00:00:00Z)
`Unsupported format`	Specify json or markdown

Approval Errors

E_APPROVAL_REQUIRED

Message: Visions with human_intervention=required need --approve. Please review the preview first

Cause: A vision with the human_intervention=required constraint was submitted without an approval token.

Resolution:

Run starweft vision submit --dry-run ... to preview
Note the approval_token from the output
Submit with starweft vision submit --approve <TOKEN> ...

E_APPROVAL_MISMATCH

Message: Preview approval token does not match

Cause: The specified approval token does not match the one generated during the preview. The vision content or constraints may have changed.

Resolution:

Re-run --dry-run to obtain a new approval token

Confirmation Errors

E_CONFIRMATION_REQUIRED

Message: --yes is required to execute stop

Cause: The confirmation flag for a destructive operation was not specified.

Resolution:

Add the --yes flag

Protocol Errors

E_PROTOCOL_VERSION

Message: Unsupported protocol_version / Unsupported protocol in received message

Cause: The protocol_version between nodes does not match.

Resolution:

Use the same version of Starweft on all nodes
Check compatibility.protocol_version in config.toml

E_SCHEMA_VERSION

Message: Unsupported schema_version

Cause: The store's schema version does not match the current runtime.

Resolution:

Update Starweft to the latest version
Check compatibility.schema_version in config.toml

E_BRIDGE_CAPABILITY_VERSION

Message: openclaw.capability_version and compatibility.bridge_capability_version do not match

Cause: There is an inconsistency in the OpenClaw capability version settings.

Resolution:

Set openclaw.capability_version and compatibility.bridge_capability_version to the same value

Delivery and Message Errors

E_MESSAGE_EXPIRED

Message: msg_id=<id> expires_at=<time> skew_sec=<sec>

Cause: A received message has exceeded its expiration time. There may be a clock skew between nodes.

Resolution:

Synchronize clocks between nodes (NTP is recommended)

E_SIGNATURE_VERIFY_FAILED

Message: Peer public key is not registered: <actor_id>

Cause: The peer's public key needed to verify the received message's signature is not registered in the store.

Resolution:

E_INVALID_MULTIADDR

Message: Invalid listen/discovery configuration / <addr>: <error>

Cause: Failed to parse the multiaddr string.

Resolution:

Verify the multiaddr format (e.g., /ip4/127.0.0.1/tcp/4001, /unix/<path>)

Stop Authority Errors

E_STOP_AUTHORITY_MISSING

Message: Stop authority key for principal not found: <path>

Cause: The stop_authority_key required for signing stop orders cannot be found.

Resolution:

Generate the stop authority key with starweft identity create --principal

OpenClaw Errors

E_OPENCLAW_NOT_FOUND

Message: Binary not found: <bin> / PATH is not set

Cause: The specified OpenClaw binary cannot be found.

Resolution:

Verify that OpenClaw is installed
Specify the full path with --bin, or add the OpenClaw directory to PATH

Backup and Restore Errors

E_BACKUP_EXISTS

Message: Backup output already exists: <path>

Cause: The backup output directory or file already exists.

Resolution:

Use the --force flag to overwrite, or specify a different output path

E_BACKUP_NOT_FOUND

Message: Backup input not found: <path>

Cause: The backup bundle to restore cannot be found.

Resolution:

Verify that the backup bundle path is correct

E_BACKUP_SIGNATURE_REQUIRED

Message: Backup requires actor_key / Cannot read actor_key for backup / manifest signature is missing

Cause: The actor_key required for signing the backup does not exist or cannot be read.

Resolution:

Create an identity with starweft identity create

E_BACKUP_SIGNATURE_INVALID

Message: signer_public_key is missing / Manifest signer_public_key does not match actor_key in the bundle / invalid registry signature

Cause: Verification of the backup manifest signature failed. The bundle may have been tampered with.

Resolution:

Verify that the backup bundle is not corrupted
Create a new backup from the original node

E_BACKUP_IDENTITY_MISMATCH

Message: Backup signer and restore destination identity do not match

Cause: The restore destination has an existing identity that differs from the backup's signer.

Resolution:

Verify that the backup is from the same node
Use the --force flag to restore a backup from a different node

E_BACKUP_MANIFEST_MISSING

Message: manifest.json not found: <path>

Cause: The backup bundle does not contain a manifest.json.

Resolution:

Specify the correct backup bundle path

E_BACKUP_MANIFEST_INVALID

Message: unsupported backup format / Bundle contains files not listed in the manifest / invalid path in manifest

Cause: The backup manifest format is invalid.

Resolution:

Use a backup created with the latest version of Starweft

E_BACKUP_CHECKSUM_MISMATCH

Message: backup entry is missing / checksum mismatch for <file>

Cause: A file in the backup bundle is missing or its checksum does not match.

Resolution:

Verify that the backup bundle is not corrupted
Create a new backup from the original node

E_RESTORE_CONFLICT

Message: Restore destination already exists: <path>

Cause: An existing file or directory exists at the restore destination.

Resolution:

Use the --force flag to overwrite, or specify a different --data-dir

Audit Errors

E_AUDIT_FAILED

Message: Inconsistencies found in task_events

Cause: The event log integrity verification detected inconsistencies.

Resolution:

Rebuild projections with starweft repair rebuild-projections
Signature errors may indicate the event log has been tampered with

Wait Errors

E_WAIT_TIMEOUT

Message: Timed out waiting for the condition to be met

Cause: The specified condition was not met within the timeout period.

Resolution:

Increase --timeout-sec
Check the node's status with starweft status or starweft logs

Registry Errors (E_REGISTRY_*)

E_REGISTRY_AUTH

Message: Various authentication errors (shared secret must not be empty, missing header, invalid signature, replayed registry nonce, etc.)

Cause: Registry authentication failed.

Resolution:

Verify that the --shared-secret value matches between the registry server and client
Check clock synchronization between nodes (the timestamp drift tolerance is limited)

E_REGISTRY_AUTH_REQUIRED

Message: non-loopback registry bind requires --shared-secret/--shared-secret-env or --allow-insecure-no-auth

Cause: No authentication is configured for binding to a non-loopback address.

Resolution:

Set a shared secret with --shared-secret or --shared-secret-env

E_REGISTRY_BIND

Message: registry bind did not resolve to any socket address

Cause: Failed to resolve the bind address.

Resolution:

Specify a valid address for --bind (e.g., 127.0.0.1:7777)

GitHub Publish Errors

E_GITHUB_TOKEN_MISSING

Message: GitHub publishing requires one of STARWEFT_GITHUB_TOKEN / GITHUB_TOKEN / GH_TOKEN

Cause: No GitHub API authentication token is set in the environment variables.

Resolution:

Set one of STARWEFT_GITHUB_TOKEN, GITHUB_TOKEN, or GH_TOKEN
See the Environment Variables reference for details

E_GITHUB_PUBLISH_FAILED

Message: status=<code> body=<response>

Cause: The GitHub API call failed.

Resolution:

Verify that the token has the appropriate scope (repo permission)
Verify that the repository name in --repo and the --issue / --pr number are correct

Status Probe Errors

E_STATUS_PROBE_FAILED

Message: <probe> probe failed

Cause: The liveness or readiness probe failed.

Resolution:

Check probe details (reasons, warnings) with starweft status --json
Verify that the node started successfully using starweft logs