Troubleshooting

Common errors and their solutions.

Build errors

protoc not found

error: failed to run custom build command for `makechain`
  Could not find `protoc` installation

Install protoc:

# macOS
brew install protobuf
 
# Ubuntu / Debian
sudo apt install protobuf-compiler
 
# Verify
protoc --version

Rust nightly required

error[E0554]: `#![feature]` may not be used on the stable release channel

Nightly 1.93+ required:

rustup install nightly
rustup default nightly

Commonware version mismatch

error: failed to select a version for `commonware-consensus`

Ensure Cargo.lock is up to date:

cargo update
cargo build

Node startup

Port already in use

Error: Address already in use (os error 48)

The default ports are 50051 (gRPC) and 50052 (p2p). Check for conflicting processes:

lsof -i :50051
lsof -i :50052

Kill the conflicting process or configure different ports via CLI flags.

Invalid network flag

Error: invalid network "prod" — expected devnet, testnet, or mainnet

Valid values: devnet, testnet, mainnet.

Validator key file errors

Error: failed to read validator key file

The file must contain a 64-character hex-encoded Ed25519 seed. For development, use --seed instead:

cargo run --bin node -- --seed 1

Message submission errors

These errors are returned synchronously by SubmitMessage (pipeline stages 1–5). See the submit pipeline for the full flow.

Envelope verification (stage 1)

Error	Cause	Solution
Hash mismatch	`BLAKE3(data) != hash`	Recompute hash from serialized `MessageData`
Invalid signature	Ed25519 verification failed	Ensure you sign the hash bytes with the correct key

Structural validation (stage 2)

Error	Cause	Solution
`missing message data`	`MessageData` is null	Populate the `data` field
`mid must be non-zero`	`mid` field is 0	Set `mid` to your Make ID
`timestamp must be non-zero`	`timestamp` is 0	Set timestamp to current epoch seconds
`missing message body`	No `oneof body` variant set	Set the appropriate body for your message type
`project name is empty`	Empty `name` in `PROJECT_CREATE`	Provide a non-empty project name
`project name too long`	Name exceeds 100 characters	Shorten the project name
`project_id must be 32 bytes`	Wrong-length project ID	Use the 32-byte BLAKE3 hash of the creation message
`ref_update: missing ref_name`	Empty ref name	Provide a ref name (for example, `refs/heads/main`)
`ref_update: new_hash must be 32 bytes`	Wrong-length commit hash	Use a 32-byte BLAKE3 hash
`commit_bundle: empty commits list`	No commits in bundle	Include at least one commit
`commit_bundle: too many commits`	More than 1,000 commits	Split into multiple bundles

Signer authorization (stage 3)

Error	Cause	Solution
Signer not registered	The signing key is not registered for the given `mid`	Submit a `KEY_ADD` message first

Network validation (stage 4)

Error	Cause	Solution
Network mismatch	Message `network` differs from node's network	Set the message network to match (for example, `devnet`)

Mempool admission (stage 5)

Error	Cause	Solution
Duplicate message	Message hash already in mempool	This message was already submitted — no action needed
Mempool full	Mempool at capacity (100,000)	Wait and retry
Timestamp too old	Message older than 10 minutes	Use a current timestamp
Timestamp too far in future	Message more than 30 seconds ahead	Fix client clock skew

State errors (execution stage)

These errors occur during block execution (stage 6) and cause the message to be silently dropped. They appear in node logs but are not returned to the submitter.

Error	Cause	Solution
`UnknownAccount`	`mid` has no registered account	Register a key first via `KEY_ADD`
`UnknownKey`	Signing key not found for `mid`	Register the key with `KEY_ADD`
`InsufficientScope`	Key scope too low for the operation	Use a key with the required scope (for example, OWNER for `PROJECT_REMOVE`)
`NotProjectOwner`	Operation requires project ownership	Only the project creator can perform this action
`NotProjectAdmin`	Operation requires admin access	The `mid` needs owner or collaborator access with admin role
`NotProjectWriter`	Operation requires write access	Add the `mid` as a collaborator or use the owner's key
`ForkAccessDenied`	Forking a private project without read access	Request collaborator access from the project owner
`AgentProjectDenied`	AGENT key not authorized for this project	Add the project to the key's `allowed_projects` list
`ProjectNotFound`	`project_id` does not exist	Verify the project ID (BLAKE3 hash of the creation message)
`ProjectRemoved`	Project has been removed	The project was deleted via `PROJECT_REMOVE`
`ProjectArchived`	Project is read-only	Archived projects do not accept writes. Create a new project or fork
`StorageLimitExceeded`	Account hit the project limit	Each storage unit allows 10 projects
`RefLimitExceeded`	Project hit the 200-ref limit	Delete unused refs before creating new ones
`CollaboratorLimitExceeded`	Project hit the 50-collaborator limit	Remove inactive collaborators
`KeyLimitExceeded`	Account hit the 100-key limit	Remove unused keys
`VerificationLimitExceeded`	Account hit the 50-verification limit	Remove old verifications
`ProjectNameTaken`	Another project by this account uses the same name	Choose a different name
`InvalidClaimSignature`	Verification signature is invalid	Re-sign the claim message `makechain:verify:<mid>` with your external key
`RefCasMismatch`	Ref has been updated since you last read it	Re-read the ref, update `old_hash`, and retry
`RefNotFound`	Ref does not exist in the project	Check the ref name spelling
`CommitNotFound`	Referenced commit hash not in the project	Push the commit bundle before updating the ref
`NotFastForward`	New commit is not a descendant of the current ref target	Rebase or merge before pushing
`RefNonceMismatch`	Ref nonce does not match expected value	Re-read the ref to get the current nonce
`AlreadyExists`	Adding an entry that already exists in a 2P set	The resource (collaborator, key, verification) is already active
`AlreadyRemoved`	Removing an entry that is already removed	No action needed — the resource is already gone

API errors

gRPC status codes returned by query endpoints:

gRPC Status	`ApiError` Variant	Common triggers
`NOT_FOUND`	`NotFound`	Invalid project ID, unknown account, missing ref
`INVALID_ARGUMENT`	`InvalidArgument`	Malformed hex string, invalid cursor, limit out of range
`INTERNAL`	`Internal`	State lock failure, unexpected storage error
`INTERNAL`	`State(...)`	State errors propagated from the execution layer