Troubleshoot NodeGit

Antora interfaces with git repositories using nodegit.
During installation (specifically the default site generator), Antora downloads and installs nodegit automatically.
But this step requires support from your system.
If Antora fails to install or run, nodegit is the most probable culprit.
This page helps you troubleshoot the problem.

Check prerequisites

If installation fails when it arrives at installing nodegit, the first thing to check is that you’ve satisfied all prerequisites.
Specifically, you must have installed the base build tools for your system (Linux and macOS only).

If you see this error, you either need to create the missing symlink or force nodegit to be recompiled instead of using a precompiled binary.
If you’re using Alpine Linux, you must force nodegit to recompile.

Option 1: Create missing symlink

To create the missing symlink, run the following command:

$ sudo ln -s /usr/lib64/libcurl.so.4 /usr/lib64/libcurl-gnutls.so.4

If that fails, run:

$ sudo ln -s /usr/lib/libcurl.so.4 /usr/lib/libcurl-gnutls.so.4

Once you’ve made that symlink, run the npm install command to install the site generator.

$ npm install -g @antora/site-generator-default@1.0

Option 2: Recompile NodeGit

If you aren’t comfortable making a system-wide change, or you’re on Alpine Linux or RHEL, you can recompile nodegit on your machine instead.

Force nodegit to recompile by passing the BUILD_ONLY=true environment variable to the npm install command.

$ BUILD_ONLY=true npm install -g @antora/site-generator-default@1.0

Be aware that recompiling nodegit will make installation take considerably longer.

What’s next?

Now that the default Antora site generator is installed, you are ready to: