Debugging the “Text file busy” Error During Docker Build with NPM Install

Debugging the “Text file busy” Error During Docker Build with NPM Install

The Issue

When building a Docker image that involves running an npm install command, you may run into a peculiar issue. The error message would appear as follows:

npm ERR! sh: 1: node-pre-gyp: Text file busy

This error is particularly vexing because it may only occur on some machines, which suggests that the issue might be specific to certain environments. Interestingly, the error can occur even if there have been no recent significant changes to your Docker or system configuration. The error seems to occur during the installation of NPM packages that run additional scripts during the installation process, like canvas or @ory/cli.

Here is a simple example to recreate the issue:


{ "name": "test", "version": "0.1.0", "author": "test", "type": "commonjs", "license": "ISC", "dependencies": { "canvas": "^2.11.2" } }


FROM node:slim WORKDIR /app COPY ./package.json ./ RUN npm install

Running the command docker build --pull --no-cache . would produce the error.

Problem Description

The issue seems to be an interaction between Docker and NPM, although it’s not clear which of the two is the root cause. This issue is particularly challenging because:

  • It’s inconsistent across different machines.
  • It occurs when installing third-party NPM packages, over which you have no control.

Unsuccessful Solutions

  1. Injecting Sleep: In some cases, inserting a sleep command may resolve issues where files are “busy”. However, since the error occurs during npm install, injecting a sleep command is not a feasible solution.
  2. Changing Storage Drive to Overlay2: Some users have suggested changing the storage drive to overlay2, but this isn’t a viable solution if you’re already using overlay2.

The Solution

The error might be related to the Node version being used in the Docker build. It has been reported that downgrading the Node version can solve this issue. Specifically, if you encounter this issue with Node 20.3, downgrading to 20.2 might resolve it.

To specify the Node version in your Dockerfile, you can modify the FROM directive like so:

FROM node:20.2-slim

So your updated Dockerfile would look like:

FROM node:20.2-slim WORKDIR /app COPY ./package.json ./ RUN npm install

After making this change, you can try running docker build --pull --no-cache . again, and the issue should be resolved.

By specifying the Node version, you ensure a consistent environment that should be free of the “Text file busy” error, at least with the Node 20.2 version. This could be a feasible solution until a fix is released for later Node versions.


The “Text file busy” error during a Docker build involving an NPM install can be a frustrating issue to debug, mainly because of its inconsistent appearance across different environments. The current effective solution involves specifying a different Node version in your Dockerfile. This approach ensures a consistent build environment and sidesteps the issue for the time being.