Troubleshooting

This document contains solutions for certain issues our users encountered in the past while using Lerna.

Import Command

Buffer problems during import

When you try to import a repository which has many commits in it there is a chance that you get an error such as:

DeprecationWarning: Unhandled promise rejections are deprecated

or

Error: spawnSync /bin/sh ENOBUFS during ImportCommand.execute

Solution:

Run lerna import with the --max-buffer flag and provide a large enough number (in bytes). At the writing of this entry the underlying default is 10MB, so you should keep this in mind.

Merge conflict commits cannot be imported

When you try to import a repository that contains merge commits that needed conflict resolutions, the import command fails with an error:

lerna ERR! execute Error: Command failed: git am -3
lerna ERR! execute error: Failed to merge in the changes.
lerna ERR! execute CONFLICT (content): Merge conflict in [file]

Solution

Run lerna import with the --flatten flag to import the history in "flat" mode, i.e. with each merge commit as a single change the merge introduced.

Failing when git tree has uncommitted changes

You will receive fatal: ambiguous argument 'HEAD': error, when the current project has uncommitted changes.

Solution

Make sure to commit all the changes you have in your lerna project, before importing any packages using lerna import.

Publish Command

Publish does not detect manually created tags in fixed mode with Github/Github Enterprise

Github and Github Enterprise use lightweight Git tags when a release is created through the web ui, while Lerna uses annotated tags.

This can cause an issue where Lerna will ignore previously published releases which have been manually performed and tagged with the Github web ui.

For example if the publish history was as follows:

• v1.1.0 was published and tagged with lerna publish
• v1.2.0 was manually published and tagged with the Github web ui
• v1.2.1 was manually published and tagged with the Github web ui

Running lerna publish now would detect v1.1.0 instead of v1.2.1 as the last released tag.

The implications of this depends on your usage of lerna publish:

• The publish prompt would use v1.1.0 as the base for major/minor/patch suggestions.
• When using the --conventional-commits flag:
  • would suggest a semver increment based on all the commits since v1.1.0 (including commits from v1.2.0, v1.2.1 etc)
  • The generated CHANGELOG.md files will repeat all the commits that have already been released in v1.2.0, v1.2.1 etc

Solution:

If possible, use lerna publish over manual releases.

For new manual releases, use git tag -a -m <version> instead of using the Github web ui.

For existing lightweight tags, they can be converted to an annotated tag using something like this:

GIT_AUTHOR_NAME="$(git show $1 --format=%aN -s)"
GIT_AUTHOR_EMAIL="$(git show $1 --format=%aE -s)"
GIT_AUTHOR_DATE="$(git show $1 --format=%aD -s)"
GIT_COMMITTER_NAME="$(git show $1 --format=%cN -s)"
GIT_COMMITTER_EMAIL="$(git show $1 --format=%cE -s)"
GIT_COMMITTER_DATE="$(git show $1 --format=%cD -s)"

git tag -a -m $1 -f $1 $1

git push --tags --force

See this Stackoverflow post for more details

Publishing to a private npm registry (Artifactory, npm Enterprise, etc)

If lerna publish is failing ensure you have the following your package.json:

	"publishConfig": {
		"registry": "https://[registry-url]"
	}

You may also need to add the following to your .npmrc file on the individual package(s):

registry = https://[registry-url]

:::info Lerna always uses npm tooling to publish packages, regardless of the npmClient set in the lerna.json file. This means that any yarn or pnpm configuration will not be detected. To ensure successful publishing to a private registry, make sure that npm is configured properly with environment variables or a .npmrc file. :::

Jest / Visual Studio Code Debugging

It is possible to debug Jest tests in a Lerna-managed package using Visual Studio Code. Debugging with breakpoints works with the vscode launch configuration below in the monorepo's <root>/.vscode/launch.json file. This example launches Jest for a single package my-package located in the monorepo.

{
    "name": "Jest my-package",
    "type": "node",
    "request": "launch",
    "address": "localhost",
    "protocol": "inspector",
    "runtimeExecutable": "${workspaceRoot}/node_modules/.bin/lerna",
    "runtimeArgs": [
        "exec",
        "--scope",
        "my-package",
        "--",
        "node"
    ],
    "args": [
        "${workspaceRoot}/node_modules/jest/bin/jest.js",
        "--runInBand",
        "--no-cache",
        "packages/my-package"
    ]
}

• --runInBand avoids parallelizing tests across multiple processes
• --no-cache helps avoid caching issues

Tested with Visual Studio Code v1.19.3 and Jest v22.1.4.