#Runtime

This page collects runtime-related error codes and common troubleshooting guidance.

#Error Codes

• RUNTIME-001
• RUNTIME-002
• RUNTIME-003
• RUNTIME-004
• RUNTIME-005
• RUNTIME-006
• RUNTIME-007
• RUNTIME-008
• RUNTIME-009

#RUNTIME-001

Failed to get remoteEntry exports.

• Error Code: RUNTIME-001

#Reasons

When the producer entry file is loaded normally, the producer will be registered in the global object (globalThis/window), which can be accessed through window[remoteEntryKey].

However, during this loading process, registered producers are inaccessible. There are four possible causes for this error:

1. The remoteEntryUrl is not right.
2. The remoteEntry file does not mount the container correctly.
3. Network problem, the resource cannot be accessed.
4. The remote type is a different format and not specified in either the plugin or in the init for the remotes details.

#Solutions

There are corresponding solutions for the reasons:

1. Check whether the remoteEntryUrl is correct.

• If using manifest, check the publicPath and remoteEntry.name fields in the manifest

2. If the project builder is rspack, check whether runtimeChunk is set in the final build configuration. If so, delete this configuration.
3. Check if the resource is externally accessible.
4. Loading a ESM remote from a non-esm host

• setting type: 'module' on the remote config

#RUNTIME-002

The remote entry interface does not contain "init"

• Error Code: RUNTIME-002

#Reasons

Cannot get the producer container init function.

A normal producer container exports { get, init }. In this load, init is undefined, so an error is thrown.

#Solutions

Troubleshoot in the following order:

1. Before loading the producer, run window[remoteEntryKey] in terminal to check whether this object is already occupied. If so, rename the producer name
2. If the project builder is rspack, check whether runtimeChunk is set in the final build configuration. If so, delete this configuration.

#RUNTIME-003

Failed to get manifest.

• Error Code: RUNTIME-003

#Reasons

Failed to load manifest.

#Solutions

1. Check whether the manifestUrl can be accessed normally
2. Check whether the manifestUrl has cross-origin issues

#RUNTIME-004

Failed to locate remote.

• Error Code: RUNTIME-004

#Reasons

No matching remote module found. This error may be caused by the following reasons:

1. The producer information is not registered in the consumer
2. requestId uses the wrong alias or name
3. A beforeRequest hook is registered and does not return the correct data

#Solutions

1. Check whether the producer information for this request is registered in the consumer
2. Compare whether the registered producer information (name/alias) is consistent with requestId
3. Check whether a beforeRequest hook is registered and fix the corresponding runtime plugin

#RUNTIME-005

Invalid loadShareSync function call from bundler runtime

• Error Code: RUNTIME-005

#Reasons

After Shared is set, the corresponding dependent library will be determined to be an asynchronous module. If the asynchronous entry is not enabled and eager: true is not set, then this error will occur.

#Solutions

Just choose one of the two:

1. Enable asynchronous entry

If the @module-federation/modern-js plug-in is used, the corresponding asynchronous entry will be enabled based on the builder type by default.

But if it is build mode, then you still need to set the asynchronous entry manually.

Next, we will demonstrate how to enable asynchronous entry.

Create the bootstrap.js file and copy the contents of the original entry file here:

+ import React from 'react';
+ import ReactDOM from 'react-dom';
+ import App from './App';
+ ReactDOM.render(<App />, document.getElementById('root'));

Modify the content of the original entry file and reference bootstrap.js instead:

+ import('./bootstrap');
- import React from 'react';
- import ReactDOM from 'react-dom';
- import App from './App';
- ReactDOM.render(<App />, document.getElementById('root'));

2. Set shared eager: true

#RUNTIME-006

Invalid loadShareSync function call from runtime

• Error Code: RUNTIME-006

#Reasons

The current shared dependency is not loaded, so loadShareSync cannot be used.

#Solutions

Just choose one of the two:

1. Use loadShare instead of loadShareSync
2. Provide the lib function to the current shared dependency

#RUNTIME-007

Failed to get remote snapshot.

• Error Code: RUNTIME-007

#Reasons

Remote entry is set to a version number rather than a resource URL, and the deployment platform does not deliver the correct data.

#Solutions

Check whether globalSnapshot contains an object with key ${moduleName}:${moduleInfo.version}. If not, check whether there is an issue in the deployment platform data delivery pipeline.

#RUNTIME-008

Failed to load script resources.

• Error Code: RUNTIME-008

#Reasons

Runtime resource loading failed. The possible reasons are network instability causing timeout, or an incorrect resource URL.

#Solutions

Check whether the resource URL is correct. If correct, check whether the network is stable. You can add a retry mechanism when the network is unstable, refer to Runtime retry.

#RUNTIME-009

Please call createInstance first.

• Error Code: RUNTIME-009

#Reason

Not use build plugin, but directly call runtime api.

#Solution

If the build plugin is used, an MF instance will be automatically created and stored in memory when the project starts. You can directly call methods of the MF instance via the .

import { loadRemote } from '@module-federation/enhanced/runtime';

loadRemote('remote1');

If the build plugin is not used, you need to manually create an MF instance before calling the corresponding API.

import { createInstance } from '@module-federation/enhanced/runtime';

const mf = createInstance({
  name: 'host',
  remotes: [
    {
      name: 'remote1',
      entry: 'http://localhost:2001/vmok-manifest.json',
    },
  ],
});

mf.loadRemote('remote1');

• What is a ModuleFederation instance?

A ModuleFederation instance is an instance of the ModuleFederation class, which contains all the functionality of the ModuleFederation runtime.

You can enter __FEDERATION__.__INSTANCES__ in the console to view the created instances.

#Common Issues (No Error Code)

#Warning: Invalid hook call. Hooks can only be called inside of the body of a function component. This could happen for one of the following reasons:

#Error Message

#Solution

This error is a React multi-instance problem, which usually occurs when react does not reuse the same instance. This problem can be avoided by setting shared and setting singleton: true singleton mode.

{
    ...
    new ModuleFederationPlugin({
            ...,
         // Default basic configuration
         // shared: [
         //   'react',
         //   'react-dom',
         //   'my-custom-module'
         // ]

         // Configuration with more specificity
            shared: {
                react: { singleton: true, },
                'react-dom': { singleton: true, },
                'my-custom-module': { singleton: true, },
                ...
            },
        })
      ])
  }

#HMR failed

• Use React Developer Tools

• If shared is provided from online host, use Module Federation DevTools, and click Enable HMR button .

#A preload for 'http://resource-url' is found, but is not used because the request credentials mode does not match. Consider taking a look at crossorigin attribute.

#Reason

When the producer URL is a manifest, loading this producer module will automatically preload the corresponding resources. If the above warning occurs, it is because the default preload does not configure credentials, while the actual load remote script carries the corresponding credentials, causing the preload to fail.

#Solution

Add a runtime plugin via runtimePlugins and configure the crossorigin attribute in the createLink hook. Its value needs to be consistent with the actual load script.

For example, to modify the crossorigin attribute of the preloaded link to anonymous:

import { ModuleFederationRuntimePlugin } from '@module-federation/runtime/types';

export default function MFLinkPlugin(): ModuleFederationRuntimePlugin {
  return {
    name: 'link-plugin',
    createLink({ url }) {
      const link = document.createElement('link');
      link.setAttribute('href', url);
      link.setAttribute('rel', 'preload');
      link.setAttribute('as', 'script');
      link.setAttribute('crossorigin', 'anonymous');
      return link
    }
  };
}