Skip to main content

Troubleshooting

Errors building with Vite​

If you are using Vite as your build tool, you may encounter problems getting your app to render, accompanied by warnings such as Module "buffer" has been externalized for browser compatibility.

Why is this happening?​

This is caused by missing Node polyfills in your bundled web application, as the ones provided by our SDK are not compatible with Vite.

How to fix this​

To resolve this issue, you can specify your own polyfills in your vite config.

1. Install vite-plugin-node-polyfills​

This package provides a number of polyfills for Node packages that are compatible with Vite.

Install with npm:

npm i --save-dev vite-plugin-node-polyfills

Install with yarn

yarn add --dev vite-plugin-node-polyfills

2. Configure Vite to use this plugin​

Navigate to your Vite config: this is typically in the root of your project and will be named either vite.config.js or vite.config.ts. From here, add the line import { nodePolyfills } from 'vite-plugin-node-polyfills' to the top, and add nodePolyfills() to the plugins array inside defineConfig. A barebones config using React may look like this: 

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import {nodePolyfills} from 'vite-plugin-node-polyfills'

export default defineConfig({
  plugins: [
    react(), 
    nodePolyfills()
  ],
})

3. Restart your server​

Typically, Vite will automatically restart the server for you and include your changes to its config file. If so, you're good to go! If not however, simply restart the server by terminating the process and re-starting using the relevant command (by default npm run dev or yarn dev in the project root).

More Troubleshooting​

hdkey-without-crypto.js - Cannot read properties of undefined (reading 'from')​

If you're encountering the following error in the browser console:

hdkey-without-crypto.js:18 Uncaught TypeError: Cannot read properties of undefined (reading 'from')
    at node_modules/ethereum-cryptography/pure/vendor/hdkey-without-crypto.js (hdkey-without-crypto.js:18:28)
    at __require (chunk-UN4YHSTI.js?v=2f4ead50:19:50)
    at node_modules/ethereum-cryptography/pure/hdkey.js (hdkey.ts:34:30)
    at __require (chunk-UN4YHSTI.js?v=2f4ead50:19:50)
    at node_modules/ethereumjs-wallet/dist.browser/hdkey.js (hdkey.ts:3:1)
    at __require (chunk-UN4YHSTI.js?v=2f4ead50:19:50)
    at node_modules/ethereumjs-wallet/dist.browser/index.js (index.ts:16:1)
    at __require (chunk-UN4YHSTI.js?v=2f4ead50:19:50)
    at index.js:1:18

This is caused by the ethereum-cryptography package, which has a dependency of the safe-buffer package. safe-buffer is missing the buffer package as a dependency. To fix this, install the buffer package into your project:

# npm 
npm install buffer

# yarn
yarn add buffer

Then restart update the vite.config.ts file to not include the Buffer polyfill:

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { nodePolyfills } from 'vite-plugin-node-polyfills'

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [
    react(),
    nodePolyfills({
      globals: {
        Buffer: false
      }
    })],
  // your config might not have this `define` section
  define: { 
    global: {},
  },
})

Finally, restart your Vite dev server and the error should be resolved.

Vite Preview - require is not defined​

If you're using vite preview and encounter the error require is not defined in the browser console. Add the following to your build section of your vite.config.ts file:

// https://vitejs.dev/config/
export default defineConfig({
  /* your existing vite config */
  build: {
    commonjsOptions: {
      transformMixedEsModules: true
    }
  },
})

This will allow Vite to transform mixed ES modules to CommonJS, which is required by the SDK.

Rebuild your project before running vite preview again.

Errors building with Webpack​

If you're using the latest version of create-react-app with Typescript SDK, you may see errors like this when trying to start up the app:

Module not found: Error: Can't resolve 'https' in '/Users/{username}/{project-name}/node_modules/@imtbl/imx-sdk/dist'
BREAKING CHANGE: webpack < 5 used to include polyfills for node.js core modules by default.
This is no longer the case. Verify if you need this module and configure a polyfill for it.

Why is this happening?​

The reason for this error is that create-react-app uses a version of webpack greater than 5, which, unlike versions < 5, does not include Node.js polyfills by default. This means that they need to be configured manually for each module that requires them.

Normally, this involves updating the webpack config file inside a project, however, create-react-app uses another package called react-scripts to manage webpack (and other build dependencies). As we cannot update the webpack config within react-scripts, we will need to override it.

How to fix this​

1. Install react-app-rewired​

This package allows us to update the webpack config file to fix the polyfill node core module error.

Install with npm:

npm install --save-dev react-app-rewired

Install with yarn:

yarn add --dev react-app-rewired

2. Install the missing dependencies​

The following missing dependencies will have to be installed: crypto-browserify, stream-browserify, assert, stream-http, https-browserify, os-browserify, url, process

Install with npm:

npm install --save-dev crypto-browserify stream-browserify assert stream-http https-browserify os-browserify url buffer process

Install with yarn:

yarn add process crypto-browserify stream-browserify assert stream-http https-browserify os-browserify url buffer

3. Override the create-react-app webpack config file​

This is how we override the webpack config file in react-scripts and tell it how to resolve the missing polyfill dependencies.

In the root folder of your project, create a new file called config-overrides.js, and add the following code to it:

const webpack = require('webpack');
module.exports = function override(config) {
  const fallback = config.resolve.fallback || {};
  Object.assign(fallback, {
    crypto: require.resolve('crypto-browserify'),
    stream: require.resolve('stream-browserify'),
    assert: require.resolve('assert'),
    http: require.resolve('stream-http'),
    https: require.resolve('https-browserify'),
    os: require.resolve('os-browserify'),
    url: require.resolve('url'),
  });
  config.resolve.fallback = fallback;
  config.plugins = (config.plugins || []).concat([
    new webpack.ProvidePlugin({
      process: 'process/browser',
      Buffer: ['buffer', 'Buffer'],
    }),
  ]);
  config.module.rules.push({
    test: /\.m?js/,
    resolve: {
      fullySpecified: false,
    },
  });
  return config;
};

4. Override package.json to include the webpack configuration​

Now, to implement the new config, we need to call react-app-rewired instead of react-scripts in the following scripts in our package.json:

  • start
  • build
  • test

This is what the package.json file looks like before:

"scripts": {
  "start": "react-scripts start",
  "build": "react-scripts build",
  "test": "react-scripts test",
  "eject": "react-scripts eject"
},

This is what it looks like after:

"scripts": {
  "start": "react-app-rewired start",
  "build": "react-app-rewired build",
  "test": "react-app-rewired test",
  "eject": "react-scripts eject"
},

Once you've done this, the development server should be up and running again.

How to deal with 'failed to parse source map' warnings​

You will still have a large amount of failed to parse source map from modules warnings. They can be ignored for now, however, should you want to get rid of them, you can disable them (see this discussion) by adding GENERATE_SOURCEMAP=false to the start script in package.json:

"scripts": {
    "start": "GENERATE_SOURCEMAP=false react-app-rewired start",
    // ...
},

Errors building with Next.js​

Elliptic package error​

When using the SDK with NextJS 13 or 14 and the page router, you might encounter the following error:

import { ec, curves } from 'elliptic';
             ^^^^^^
SyntaxError: Named export 'curves' not found. The requested module 'elliptic' is a CommonJS module, which may not support all module.exports as named exports.

Why is this happening?​

This error is caused by the elliptic package (used in some SDK Stark functions), which is a CommonJS package. NextJS has experimental support for ESM externals, which is enabled by default. This feature is not yet stable and can cause issues with some packages.

How to fix this​

You can fix it by adding the following to your next.config.js:

const nextConfig = {
  // ... other next config
  experimental: {
    esmExternals: false,
  },
};

NextJS 13 with the App Router​

Currently, there is an issue with importing SDK modules and NextJS 13 using the App router. Importing SDK modules like this will cause NextJS to throw an error from the development server:

// This will not work
import { config, passport, x } from '@imtbl/sdk';

const { Environment, ImmutableConfiguration } = config;
const { Passport } = passport;
const { imxClientConfig, IMXClient } = x;

Importing SDK modules using the SDK Code Splitting method will fix this issue:

import { Environment, ImmutableConfiguration } from '@imtbl/sdk/config';
import { Passport } from '@imtbl/sdk/passport';
import { imxClientConfig, IMXClient } from '@imtbl/sdk/x';

Error reading 'fromMasterSeed' of undefined when creating wallet connection or generating legacy StarkKey​

When using the SDK with NextJS 12, you might encounter the following error:

Error creating wallet connection TypeError: Cannot read properties of undefined (reading 'fromMasterSeed')
    at getPrivateKeyFromPath (file:///.../node_modules/@imtbl/sdk/dist/index.js:17536:10)
    at getKeyFromPath (file:///.../node_modules/@imtbl/sdk/dist/index.js:17543:28)
    at Object.generateLegacyStarkPrivateKey (file:///.../node_modules/@imtbl/sdk/dist/index.js:17617:23)

Why is this happening?​

This error is caused by the ethereumjs-wallet package (used in the SDK's Stark function getPrivateKeyFromPath), which is a CommonJS package. Next.js has experimental support for ESM externals, which is enabled by default. This feature is not yet stable and can cause issues with some packages.

How to fix this​

You can fix it by adding the following to your next.config.js:

const nextConfig = {
  // ... other next config
  experimental: {
    esmExternals: false,
  },
};

You may encounter a similar error even when not using Next.js. See the demonstration and resolution here.

"Could not detect network" error on Next.js 14 API endpoint with JsonRpcProvider​

When using Next.js 14 and setting up JsonRpcProvider with ethers v5, you may encounter this error as described here.

How to Fix This​

You can fix it by downgrading to Next.js 13, upgrading to Ethers v6, or using the solution provided here in the ethers.js GitHub issue discussion.

Additional Issues​

What regions does Immutable Typescript SDK and Passport support?​

Passport is a globally available product. However, our wallet infrastructure is subject to the regulation of the US Department of the Treasury’s Office of Foreign Assets Control (“OFAC”). OFAC administers and enforces comprehensive and targeted economic and trade sanctions programs on multiple countries and regions.

To learn more about the U.S. Treasury and the Office of Foreign Assets Control (“OFAC”), please visit their website.

Users attempting to access Passport in any of the regions under OFAC sanction will have their access blocked and will be unable to use our product. Additionally, components of Passport's infrastructure also rely on technology provided by Magic, which maintains further details regarding unsupported regions on their website here.

IMX Whitepaper • IMX Tokenomics • Block Explorer • Careers • Contact Us