Error handling
Handle MeshkitError and MeshkitNodeError in your application.
Meshkit uses two error classes. Both extend the native Error.
MeshkitError
Thrown when an operation fails across all attempted nodes. The .causes array contains the individual error from each node that was tried.
import { MeshkitError } from '@ipfs-meshkit/meshkit';
try {
const cid = await meshkit.upload(bytes);
} catch (err) {
if (err instanceof MeshkitError) {
console.error('All nodes failed:', err.message);
for (const cause of err.causes) {
console.error(' -', cause.message);
}
}
}err.message is a single concatenated string; err.causes gives you the per-node errors for structured logging.
Decryption failures
retrieve with a password throws MeshkitError when the password is wrong or the EMSH payload was modified. The message is the same in both cases:
import { MeshkitError } from '@ipfs-meshkit/meshkit';
try {
await meshkit.retrieve(cid, { password });
} catch (err) {
if (err instanceof MeshkitError) {
// "Decryption failed: wrong password or corrupted data"
console.error(err.message);
}
}encrypt also throws MeshkitError when password is empty or iterations is below 1,000.
MeshkitNodeError
Thrown during daemon lifecycle operations — startIPFSNode, stopIPFSNode, or internal daemon health checks. Includes a .cause property (native Error) when a lower-level error triggered it.
import { MeshkitNodeError } from '@ipfs-meshkit/meshkit';
try {
const { meshkit, localNode } = await init({ localNode: true });
} catch (err) {
if (err instanceof MeshkitNodeError) {
console.error('Daemon failed to start:', err.message);
}
}init() errors
init() throws a plain MeshkitError (not a node error) when:
- No node URLs are provided and
localNodeis not set - All provided nodes fail the health check at startup
// throws: At least one node URL is required
await init({});
// throws: MeshkitError if all nodes are unreachable
await init({ nodes: ['http://unreachable:5001'] });Type narrowing
Both error classes set err.name explicitly:
if (err instanceof MeshkitError) {
// err.name === 'MeshkitError'
// err.causes: Error[]
}
if (err instanceof MeshkitNodeError) {
// err.name === 'MeshkitNodeError'
// err.cause?: unknown
}