Common Errors

If the suggested steps here don't work, please open an issue or post your questions in the #web5 channel on TBD Discord.

UnhandledSchemeError: Reading from "node:crypto" is not handled by plugins (Unhandled scheme)

This is an issue with Webpack that happens mostly in Next.js projects. Here's how to solve it:

1. Run the following command to install three packages that will enable cryptographic functions and stream handling within the browser:

npm install crypto-browserify stream-browserify process

2. Then, in your next.config.js file, add the following:

const webpack = require('webpack');

/** @type {import('next').NextConfig} */
const nextConfig = {
  reactStrictMode: true,

  webpack: (config, { isServer, buildId, dev, webpack }) => {
    if (!isServer) {
      config.resolve.fallback = {
        ...config.resolve.fallback,
        stream: require.resolve('stream-browserify'),
        crypto: require.resolve('crypto-browserify'),
      };

      config.plugins.push(
        new webpack.ProvidePlugin({
          process: 'process/browser',
        }),
        new webpack.NormalModuleReplacementPlugin(/node:crypto/, (resource) => {
          resource.request = resource.request.replace(/^node:/, '');
        }),
      );
    }
    return config;
  },
};

module.exports = nextConfig;

ReferenceError: process is not defined

When starting up and connecting to the Web5 SDK, some polyfills might be missing. To fix this, update your Web5 import:

import { Web5 } from '@web5/api/browser';

ProtocolAuthorizationIncorrectProtocolPath: Declared protocol path 'x' is not the same as actual protocol path 'y/x'

This could happen for a few reasons when working with protocols. Here are the debugging steps you could take:

• Confirm that the protocolPath in your message object is correct and matches the protocol path you declared in your protocol definition.
• Next check that you are not missing a parentId attribute when sending your request. This is a common mistake when creating a record in a protocol. For example, if you are creating a todo item in a todo list, you need to pass the parentId of the todo list to the todo item. Here's an example:

await web5.dwn.records.create({
  data: todoData,
  message: {
    protocol: protocolDefinition.protocol,
    protocolPath: 'list/todo',
    schema: protocolDefinition.types.todo.schema,
    dataFormat: protocolDefinition.types.todo.dataFormats[0],
    parentContextId: listId.value,
  },
});

Error: 'undefined' is not supported by the IPLD Data Model and cannot be encoded

This is a syntax error in the calling functon that causes the error. Check this function for any typos or missing attributes.

Error: connect() failed due to unexpected state: ${storedIdentities} stored identities

This error happens when you try to connect to the Web5 SDK, but there are multiple stored identities in the application's data store, which causes a conflict during the connection process.

Since identities are stored in the browser memory, you can resolve this issue by clearing your browser's cache. Clearing the browser's cache will remove all stored identities and reset the application's state.

Error: PrivateKeyStoreDwn: Failed to write imported DID to store

This error happens with Node versions prior to version 20.

To fix these errors, upgrade to Node 20.9.0 or later.

If you're unable to upgrade, add the following to your file:

import { webcrypto } from "node:crypto";
import { Web5 } from "@web5/api";

// @ts-ignore
if (!globalThis.crypto) globalThis.crypto = webcrypto;

Error: TypeError: Cannot read properties of undefined (reading 'verificationMethodKeys')

This error occurs when you attempt to sign a verifiable credential using the String version of a DID. To resolve this, sign with a Portable DID so that your private key is used to cryptographically sign the credential.

Error: ProtocolAuthorizationProtocolNotFound: unable to find protocol definition

This error occurs when attempting to interact with a DWN that does not have the required protocol installed. To solve this, ensure both parties have successfully installed the protocol definition.

Error: Wrong tag

This error occurs due to a mismatch between encryption and decryption keys. To resolve:

• In a browser: Clear the browser cache and retry.
• In a Node.js app: Delete the DATA folder and retry.