Failed to acquire lock for plugin installation

[highfalutin]

I'm trying to get Etherpad up and running via docker compose. I'm able to log in to the admin page. But when I try to install a plugin, it fails silently. On the backend, I see this log entry:

app-1 | [2026-07-06T07:08:58.981] [WARN] plugins - Failed to install plugin ep_headings2: Failed to acquire lock: EACCES: permission denied, open '/opt/etherpad-lite/src/plugin_packages/install.lock'

and here's what I see when I inspect that path:

> docker exec etherpad-lite-app-1 ls -al /opt/etherpad-lite/src/plugin_packages/
total 8
drwxr-xr-x    2 root     root          4096 Jul  2 15:56 .
drwxr-xr-x    1 etherpad root          4096 Jul  6 07:08 ..

I don't know whether or how to change the ownership of that directory inside the docker container. Any help would be appreciated.

[alazarlemma02]

Hi @highfalutin

This looks like a permissions problem on the Docker named volume used for plugins.

We are running as UID 5001, but the mounted plugin directory is owned by root:root and is not writable by that user:

drwxr-xr-x    2 root root 4096 Jul  2 15:56 .

When the admin UI tries to install a plugin, Etherpad needs to create:

/opt/etherpad-lite/src/plugin_packages/install.lock

Since that directory is not writable, the install fails with EACCES.

As a workaround, you can fix the ownership of the mounted plugin volume once:

docker compose exec --user root app chown -R 5001:0 /opt/etherpad-lite/src/plugin_packages
docker compose restart app

Then try installing the plugin again from the admin UI.

If the service name in your Compose project is different, replace app with the actual service name from docker compose ps.

This also looks like something we should improve in the Docker setup or docs, because a fresh named volume should not leave runtime plugin installation unable to create its lock file.

Thanks.

[highfalutin]

Thanks, the commands you provided seem to have fixed the issue.

Do you have any idea how the ownership of the directory ended up incorrect?

[alazarlemma02]

Great, glad that fixed it.

My guess is that this came from Docker’s named volume initialization rather than anything you did manually.

The Compose setup mounts a named volume here:

plugins:/opt/etherpad-lite/src/plugin_packages

Once that volume is mounted, it hides whatever ownership/permissions existed for that path inside the image. If Docker creates the named volume with a root-owned directory, or if it was created earlier by a container running as root, that ownership persists across container restarts and recreates.

So even though Etherpad itself runs as UID 5001, the mounted directory can still end up as:

root:root

and then Etherpad cannot create install.lock.

The important part is that named volumes are persistent. Recreating the container does not reset the volume ownership. Running the chown command fixed the existing volume in place, which is why plugin installation works now

This is probably worth improving, either we can document the expected ownership or make the Docker setup initialize the plugin volume permissions more reliably

Thanks.

[JohnMcLear]

@alazarlemma02 Thanks for your input! I'd like to see this properly fixed if possible please.

[alazarlemma02]

Thanks, @JohnMcLear

I’ll take a closer look at the Docker Compose/image setup and try to identify the smallest safe change that ensures the plugin_packages volume is writable by the Etherpad runtime user. I’ll keep the change scoped to this issue and verify it with a local Docker Compose reproduction.