succi0303 blog

This is my personal blog. All posts are my own.

Cause and Recovery of Paperless-ngx Failure on Docker (Disabled rclone Plugin)

english

I run Paperless-ngx as a Docker application on my home server.
One day, I suddenly could not access it.
When I tried to restart the stack from Portainer, it failed with an error and the service could not start.
This article documents the steps from the occurrence of the issue to its resolution.

Incident

Accessing Paperless-ngx from the browser resulted in a connection error.
When attempting to stop and restart the stack from Portainer’s management console, the following error message appeared:

Failed to deploy a stack: compose up operation failed: 
Error response from daemon: get paperless-ngx_media: 
error while checking if volume "paperless-ngx_media" exists in driver "rclone:latest": 
error looking up volume plugin rclone:latest: plugin rclone:latest found but disabled

Environment

Paperless-ngx is deployed using docker-compose.yml, with the media, export, and consume volumes mounted to OneDrive using the rclone volume plugin.

volumes:
  media:
    driver: rclone
    driver_opts:
      remote: "onedrive:paperless/media"
      allow_other: "true"
      vfs_cache_mode: "full"
      poll_interval: 0

Investigation

The error message showed:

plugin rclone:latest found but disabled

This indicated that the rclone plugin existed but was disabled.
I checked the plugin status with:

docker plugin ls

Example output:

ID                  NAME                DESCRIPTION               ENABLED
abcd1234abcd        rclone:latest       Rclone Volume Plugin      false

As expected, ENABLED was false.
It seems that Docker plugins can become disabled after a host reboot or Docker daemon restart.

Recovery

By re-enabling the plugin, the stack was able to start normally:

docker plugin enable rclone:latest

Afterwards, redeploying the stack from Portainer succeeded, and I was able to access Paperless-ngx from the browser again.

Preventing Recurrence

  • Check plugin enablement
    • During an incident, first check docker plugin ls to ensure ENABLED is true.
  • Beware of Docker restarts
    • Plugins may be disabled after a host or Docker daemon restart.
  • Alternative approach
    • For more stability, consider avoiding docker plugin and instead run rclone mount as a systemd service, then bind-mount the directory into containers.

Conclusion

  • The cause of the Paperless-ngx stack failure was that the rclone plugin was disabled.
  • Running docker plugin enable rclone:latest restored service.
  • When using Docker plugins, keep in mind that they may be disabled after restarts.