Reference
Errors
MeshKitError categories and fixes.
MeshKit throws MeshKitError when it can classify a failure. Handle errors by reading code, message, suggestion, and sanitized details.
import { MeshKitError, createMeshkit } from "@meshkit/core";
const mesh = await createMeshkit();
try {
await mesh.share.openCapsule("missing-capsule");
} catch (error) {
if (error instanceof MeshKitError) {
console.error(error.code);
console.error(error.suggestion);
}
}Error Categories
| Category | Codes | First action |
|---|---|---|
| Configuration | invalid_config, invalid_cli_config | Validate config shape and environment variables |
| Provider | provider_http_error, provider_request_failed | Check endpoint, token, network, timeout, and sanitized response |
| Integrity | invalid_envelope, CID mismatch failures | Confirm bytes and metadata come from the same provider boundary |
| Identity | identity_not_found, recipient_not_authorized, key_unwrap_failed | Check local identity, recipient public key, and capsule wraps |
| Sharing | capsule_not_found, share_expired, share_revoked | Confirm capsule metadata, expiry, and revocation state |
| Policy | policy_provider_required, policy_provider_error, policy_denied | Configure policy provider or update membership |
| Capabilities | capability_required, capability_denied | Pass or reissue the required capability token |
| Streaming | invalid_chunk_size, invalid_stream_resume_token, operation_aborted | Check stream options and resume token provenance |
| Persistence | persistence_not_configured | Configure a persistence provider |
| MCP input | invalid_tool_input, input_too_large | Fix schema input or reduce payload size |
Safe Logging
Safe:
error.codeerror.suggestion- CID
- provider name
- capsule ID
- proof summary
Unsafe:
- decrypted content
- private keys
- provider tokens
- bearer headers
- capability token secrets
- unredacted provider response bodies
Troubleshooting Flow
- Identify the error code.
- Identify the boundary: config, provider, metadata, identity, policy, runtime, or input.
- Run
mesh.doctor.run()or CLImeshkit doctor --json. - Confirm the CID, capsule, mailbox, or sync record exists in the same provider boundary.
- Fix the boundary before changing encryption logic.