SDK Troubleshooting
Symptom-first fixes for SDK integration issues.
Start with the error code and the provider boundary. MeshKit classifies many failures as MeshKitError with a code, message, and suggestion.
import { MeshKitError, meshkit } from "@meshkit/meshkit";
const mesh = await meshkit();
try {
await mesh.files.get("bafk-missing-or-wrong-cid");
} catch (error) {
if (error instanceof MeshKitError) {
console.error(error.code);
console.error(error.suggestion);
}
}Do not fix SDK issues by logging plaintext, private keys, bearer tokens, capability token secrets, or full provider responses.
Quick Triage
| Symptom | Most likely boundary | What to check first |
|---|---|---|
| Package cannot be imported | Install/package name | Use @meshkit/meshkit, not unscoped meshkit |
| Local quickstart works, production read fails | Provider and metadata service | Confirm the same MeshKit provider boundary created and reads the CID |
| CID exists but cannot decrypt | Identity or share capsule | Confirm the current identity has a wrapped key or capsule |
| Share opens for owner but not recipient | Recipient identity | Create, import, publish, or resolve the recipient identity |
| Message inbox is empty | Provider mailbox | Confirm mailbox support and recipient ID |
| Stream resume fails | Resume token | Use a token from the same direction, CID, name, chunk size, and manifest |
| Sync job never runs | App scheduler | Call flush from a real runtime background or foreground path |
| Doctor fails only in CI | Environment and secrets | Check provider tokens, env vars, network access, and secret redaction |
Common Error Codes
| Code | Meaning | Fix |
|---|---|---|
invalid_config | MeshKit options or config are inconsistent | Validate meshkit.config.json and runtime options |
invalid_cli_config | CLI config cannot be parsed or used | Re-run CLI init or repair the config file |
provider_http_error | Provider returned an HTTP failure | Check endpoint, credentials, request body, and sanitized response |
provider_request_failed | Provider request failed before a valid response | Check network, DNS, TLS, retries, and timeout |
identity_not_found | MeshKit cannot find the requested identity | Create/import identity or configure a directory |
recipient_not_authorized | Recipient does not have access to the content | Create a new share capsule or update membership |
key_unwrap_failed | Current identity cannot unwrap the content key | Open as the right identity or verify the capsule |
capsule_not_found | Share capsule ID is missing from metadata | Ask sender to resend or check provider metadata |
share_expired | Capsule expiry passed | Create or request a new capsule |
share_revoked | Capsule was revoked | Create a new share if access should resume |
policy_provider_required | Opening depends on a policy provider | Configure the provider used to create the capsule |
policy_denied | Policy provider denied access | Update policy membership or issue a new share |
capability_required | A capability token is required | Pass the token issued by the vault or capability owner |
invalid_stream_resume_token | Resume token does not match the operation | Restart or use a fresh token from the same stream |
sync_not_supported | Provider cannot store sync jobs | Use a provider with sync queue support |
Provider And Metadata Problems
MeshKit production workflows need more than raw bytes. The provider boundary must preserve encrypted bytes and the MeshKit metadata used for proofs, capsules, mailboxes, sync jobs, vaults, capabilities, logs, and health checks.
If reads fail in production:
- Confirm the CID came from this MeshKit environment.
- Confirm the byte provider can retrieve the encrypted envelope.
- Confirm the metadata service has the proof and any required capsule or mailbox record.
- Run
mesh.doctor.run()in app code ornpx -p @meshkit/cli meshkit doctor --jsonfrom the terminal. - Check
MeshKitError.codebefore changing encryption or identity logic.
Identity And Sharing Problems
MeshKit identities are application-level encryption identities. They are not automatically emails, wallets, DIDs, or passkeys.
When sharing fails:
- Verify the sender created or resolved the recipient public key before creating the capsule.
- Open the capsule as the intended recipient with
openCapsule(capsule, { as: "recipient" }). - Confirm the capsule is not expired or revoked.
- If policy, vault, or capability fields are present, configure and pass those requirements.
Local Works, Production Fails
Local development defaults are intentionally forgiving. Production adds real provider boundaries:
- Credentials can be missing or scoped incorrectly.
- A Kubo or gateway path can store bytes but not MeshKit metadata.
- Browser and mobile apps should not connect directly to unrestricted Kubo RPC.
- Filecoin deal state does not guarantee immediate retrieval.
- Mobile native vault behavior depends on the runtime bridge actually installed.
Use Production setup and Provider testing before shipping.
Safe Debug Output
Safe to log:
MeshKitError.codeMeshKitError.suggestion- CID
- provider name
- proof summary
- capsule ID
- sync job ID
Do not log:
- plaintext
- private keys
- bearer tokens
- capability token secrets
- full provider response bodies that may contain credentials