Troubleshooting Component Isolation

There are several issues you may encounter when Bit tries to isolate components in a project.


To validate a dependency issue is resolved, rerun bit status.

Missing package dependencies

This error mainly occur on two distinct isolation issues. It may be that some of the project’s package dependencies are not installed, or that you are using Custom Module Definition, or NODE_PATH environment variable in your project and Bit is unaware of that.

Installing missing packages dependencies

As described in this section, Bit has different strategies to determine a package dependency version. If all of them fail, Bit will prompt you to install the missing package dependencies.
Use your package manager of choice to resolve the issue.

npm install

Configuring Custom Module Resolution

Bit issues a missing package dependency error for tracked components, in a project, that have file dependencies to absolute paths, using Custom Module Definition feature, such as:

This is because by default Bit handle absolute import or require statements as package dependencies, and relative paths as file dependencies. So in this case, in your code, you are using an absolute path to require a file.

To resolve this issue, you will need to configure Bit’s Custom Module Resolution so that Bit will be able to resolve the paths to the files correctly.

Open your project’s bit.json file, and configure a resolveModules object in it, similar to this example. Note that you can use it to either configure aliases, using the alias configuration. Or, if you use NODE_PATH environment variable to point to specific directories within a project, you need to set the modulesDirectories array, and populate it with an array of paths. You can use a combination of both, as shown here:

"resolveModules": {
    "modulesDirectories": ["src/utils"],
    "aliases": {
        "@": "src/components"

You can read more about it here.

Untracked file dependencies

This isolation error occur when one of the component’s tracked files has a file dependency that is not tracked by Bit. There are several ways to resolve this issue, choose one of the option that goes with the specific implementation of your component and project.

Learn more about tracking components with file dependencies.

Adding the untracked file dependency to an already tracked component

If you’ve decided that the specific file(s) is part of the component implementation, you can add it to the newly tracked component (or any other component). The bit add command allows you to append files to tracked component by specifying the pre-existing component-ID.

The following example will add the file src/utils/noop.js to the component hello/world.

bit add src/utils/noop.js --id hello/world

Learn more about this issue.

Tracking an untracked file dependency as a new component

In some cases, an untracked file dependency should be a separate component, as other components may use it. If you decide that this is the solution, you need to track a new component. This component will include the untracked file (a component can contain a single file). Once you track the file dependency as a component (or a part of another component), Bit will create a dependency relationship between both components.

bit add src/utils/noop.js

[Learn more](docs/isolating-and-tracking-components.html#track-an-untracked-file-dependency-as-a component-dependency) about this issue.

Components with Relative Import Statements

Bit expects the dependency tree of components to be defined using absolute require or import statements. This is because Bit create and manage a set of link files (bindings) between imported components. So when you are using an imported component from another tracked component, or modifying an imported component, and adding an import statement to another imported component, Bit will trigger this isolation issue.

In order to resolve this, you need to understand that Bit creates a link file for each of the project’s imported component within the node_modules directory. This allows you to require a component just as you would require a Bit package dependency with the same name, as shown here.

To resolve this issue you will need to refactor the import or require statement in your code to the component dependencies, using Bit’s package naming convention, and save the changes.

require ('@bit/<owner>.<scope>.<namespace>.<component-name>')

Missing Components

This issue happens if some (or all) of your project component dependencies are missing. To resolve it you need to either run bit import or npm install (depends how your project depends on the component).

Non-existing Dependency Files

When Bit tracks files in your project, it evaluates their dependency tree. If one of the files in the component’s dependency tree is not found within your project, Bit will throw this isolation error. To resolve this issue, open the file, and ensure that the import or require statement points to the correct file.
If you encounter this issue, this indicates that there’s a high probability that this is because an error within your project that affects your project’s stability.

When Bit installs components, it creates a set of binding files to ensure that all imported component’s dependency trees are working correctly. If any of these files is missing, Bit will prompt this isolation error. To fix this, you need to run the bit bind command. Bit will ensure all link files are in place.