CLI Troubleshooting

Use this page when a MeshKit CLI command fails, returns unexpected state, or produces output that does not match the environment you intended to test.

Start by rerunning the command with --json. Structured errors include a code and suggestion when MeshKit can classify the failure.

npx -p @meshkit/cli meshkit doctor --config meshkit.config.json --json

Fast Triage

Symptom	Likely cause	Fix
Command uses the wrong config	Current directory, `MESHKIT_CONFIG`, or `--config` points elsewhere.	Pass `--config` explicitly and print the path in CI logs.
`inspect` cannot find a CID written earlier	The command is using a different local-dev store or metadata service.	Pass the same `--store` or provider config used by `dev put`.
Local works but CI fails	CI lacks config files, tokens, or writable local-dev path.	Provide `MESHKIT_CONFIG`, token env vars, and an explicit `--store` path.
Provider test passes but app workflow fails	CLI doctor is narrower than the shipped SDK workflow.	Validate write, read, proof, sharing, policy, and cleanup in the actual runtime.
Output includes sensitive data	Debug command or logs captured plaintext or tokens.	Rotate exposed secrets and remove unsafe artifacts.

Error Codes

Code	Meaning	Fix
`invalid_cli_config`	Config file is malformed, missing `version: 1`, or uses unsupported provider fields.	Fix `meshkit.config.json` or pass a different file with `--config`.
`missing_cid`	`meshkit inspect` was called without a CID.	Pass the CID returned by `meshkit dev put` or the SDK.
`unknown_command`	The first command token is not supported.	Run `meshkit help` and compare with Commands.
`missing_deal_id`	A Filecoin deal command needs a deal ID.	Pass the deal ID returned by persistence workflow output.
`invalid_duration_days`	Renewal duration is not a positive integer.	Pass `--duration-days 180` or omit the flag.
`missing_output_path`	Retrieval needs an output file.	Add `--output <path>`.
`missing_policy_id`	Policy audit needs a policy ID.	Pass the ID returned by the policy provider.
`cli_error`	A non-MeshKit error escaped.	Check the message, filesystem access, and package installation.

Provider and SDK failures may also surface codes such as provider_http_error, provider_request_failed, persistence_not_configured, policy_not_configured, identity_not_found, recipient_not_authorized, or key_unwrap_failed.

Config Problems

Validate the minimum config shape:

{
  "version": 1,
  "appId": "mk_local_dev",
  "provider": {
    "type": "local-dev",
    "store": ".meshkit/local-dev.json"
  }
}

Then run:

npx -p @meshkit/cli meshkit doctor --config meshkit.config.json --store .meshkit/local-dev.json --json

If this works, add live provider fields one at a time. For live IPFS providers, remember that MeshKit needs both ipfsApiUrl and metadataApiUrl.

Token Problems

Use tokenEnv in config:

{
  "type": "ipfs-http",
  "ipfsApiUrl": "https://ipfs-api.example.com",
  "metadataApiUrl": "https://meshkit-metadata.example.com",
  "tokenEnv": "MESHKIT_PROVIDER_TOKEN"
}

Then set the token in the environment that launches the CLI. Do not commit token values into meshkit.config.json.

Local-Dev State Problems

If local proof inspection behaves inconsistently, make the state path explicit:

npx -p @meshkit/cli meshkit dev put repro.txt "repro" --store .meshkit/repro.json --json
npx -p @meshkit/cli meshkit inspect <cid> --store .meshkit/repro.json --json

Use a new store path for clean reproductions. Preserve the old store when you need evidence for a bug report.

Provider Problems

Run both:

npx -p @meshkit/cli meshkit providers test --json
npx -p @meshkit/cli meshkit logs --json

If the provider stores bytes but proof inspection fails, check the metadata service first. A Kubo, Cluster, gateway, or pinning service can move encrypted bytes without satisfying MeshKit's metadata contract.

Safe Reporting

Include these in issues or release evidence:

Command, exit code, package version, and OS/runtime.
Redacted config shape.
Error code, message, suggestion, and sanitized details.
CID, deal ID, provider type, and proof summary when relevant.

Remove these before sharing:

Bearer tokens and secret environment values.
Private keys, exported identity secrets, capability token secrets.
Plaintext payloads passed to dev put.
Retrieved content written by deals retrieve.

CLI Troubleshooting

On this page