Stirling-Tools
[Bug]: unraid permissions or container issue
Installation Method
Docker
The Problem
The container never fully starts. Please see logs. I can't ascertain if this is a permissions issue on unraid or if its something else related to the container or template.
Version of Stirling-PDF
Latest
Last Working Version of Stirling-PDF
No response
Page Where the Problem Occurred
No response
Docker Configuration
Relevant Log Output
Picked up JAVA_TOOL_OPTIONS: -XX:+UnlockExperimentalVMOptions -XX:MaxRAMPercentage=75 -XX:InitiatingHeapOccupancyPercent=20 -XX:+G1PeriodicGCInvokesConcurrent -XX:G1PeriodicGCInterval=10000 -XX:+UseStringDeduplication -XX:G1PeriodicGCSystemLoadThreshold=70
Traceback (most recent call last):
File "/opt/venv/bin/unoserver", line 8, in <module>
sys.exit(main())
^^^^^^
File "/opt/venv/lib/python3.12/site-packages/unoserver/server.py", line 414, in main
with tempfile.TemporaryDirectory() as tmpuserdir:
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "/usr/lib/python3.12/tempfile.py", line 886, in __init__
self.name = mkdtemp(suffix, prefix, dir)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "/usr/lib/python3.12/tempfile.py", line 373, in mkdtemp
prefix, suffix, dir, output_type = _sanitize_params(prefix, suffix, dir)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "/usr/lib/python3.12/tempfile.py", line 126, in _sanitize_params
dir = gettempdir()
^^^^^^^^^^^^
File "/usr/lib/python3.12/tempfile.py", line 315, in gettempdir
return _os.fsdecode(_gettempdir())
^^^^^^^^^^^^^
File "/usr/lib/python3.12/tempfile.py", line 308, in _gettempdir
tempdir = _get_default_tempdir()
^^^^^^^^^^^^^^^^^^^^^^
File "/usr/lib/python3.12/tempfile.py", line 223, in _get_default_tempdir
raise FileNotFoundError(_errno.ENOENT,
FileNotFoundError: [Errno 2] No usable temporary directory found in ['/tmp', '/var/tmp', '/usr/tmp', '/']
cp: can't stat '/usr/share/tesseract-ocr/5/tessdata/*': No such file or directory
Picked up JAVA_TOOL_OPTIONS: -XX:+UnlockExperimentalVMOptions -XX:MaxRAMPercentage=75 -XX:InitiatingHeapOccupancyPercent=20 -XX:+G1PeriodicGCInvokesConcurrent -XX:G1PeriodicGCInterval=10000 -XX:+UseStringDeduplication -XX:G1PeriodicGCSystemLoadThreshold=70
Traceback (most recent call last):
File "/opt/venv/bin/unoserver", line 8, in <module>
sys.exit(main())
^^^^^^
File "/opt/venv/lib/python3.12/site-packages/unoserver/server.py", line 414, in main
with tempfile.TemporaryDirectory() as tmpuserdir:
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "/usr/lib/python3.12/tempfile.py", line 886, in __init__
self.name = mkdtemp(suffix, prefix, dir)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "/usr/lib/python3.12/tempfile.py", line 373, in mkdtemp
prefix, suffix, dir, output_type = _sanitize_params(prefix, suffix, dir)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "/usr/lib/python3.12/tempfile.py", line 126, in _sanitize_params
dir = gettempdir()
^^^^^^^^^^^^
File "/usr/lib/python3.12/tempfile.py", line 315, in gettempdir
return _os.fsdecode(_gettempdir())
^^^^^^^^^^^^^
File "/usr/lib/python3.12/tempfile.py", line 308, in _gettempdir
tempdir = _get_default_tempdir()
^^^^^^^^^^^^^^^^^^^^^^
File "/usr/lib/python3.12/tempfile.py", line 223, in _get_default_tempdir
raise FileNotFoundError(_errno.ENOENT,
FileNotFoundError: [Errno 2] No usable temporary directory found in ['/tmp', '/var/tmp', '/usr/tmp', '/']
cp: can't stat '/usr/share/tesseract-ocr/5/tessdata/*': No such file or directory
Picked up JAVA_TOOL_OPTIONS: -XX:+UnlockExperimentalVMOptions -XX:MaxRAMPercentage=75 -XX:InitiatingHeapOccupancyPercent=20 -XX:+G1PeriodicGCInvokesConcurrent -XX:G1PeriodicGCInterval=10000 -XX:+UseStringDeduplication -XX:G1PeriodicGCSystemLoadThreshold=70
Traceback (most recent call last):
File "/opt/venv/bin/unoserver", line 8, in <module>
sys.exit(main())
^^^^^^
File "/opt/venv/lib/python3.12/site-packages/unoserver/server.py", line 414, in main
with tempfile.TemporaryDirectory() as tmpuserdir:
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "/usr/lib/python3.12/tempfile.py", line 886, in __init__
self.name = mkdtemp(suffix, prefix, dir)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "/usr/lib/python3.12/tempfile.py", line 373, in mkdtemp
prefix, suffix, dir, output_type = _sanitize_params(prefix, suffix, dir)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "/usr/lib/python3.12/tempfile.py", line 126, in _sanitize_params
dir = gettempdir()
^^^^^^^^^^^^
File "/usr/lib/python3.12/tempfile.py", line 315, in gettempdir
return _os.fsdecode(_gettempdir())
^^^^^^^^^^^^^
File "/usr/lib/python3.12/tempfile.py", line 308, in _gettempdir
tempdir = _get_default_tempdir()
^^^^^^^^^^^^^^^^^^^^^^
File "/usr/lib/python3.12/tempfile.py", line 223, in _get_default_tempdir
raise FileNotFoundError(_errno.ENOENT,
FileNotFoundError: [Errno 2] No usable temporary directory found in ['/tmp', '/var/tmp', '/usr/tmp', '/']
Running Stirling PDF with DOCKER_ENABLE_SECURITY=false and VERSION_TAG=0.46.2
Setting permissions and ownership for necessary directories...
Copying original files without overwriting existing files
running with JAVA_TOOL_OPTIONS -XX:+UnlockExperimentalVMOptions -XX:MaxRAMPercentage=75 -XX:InitiatingHeapOccupancyPercent=20 -XX:+G1PeriodicGCInvokesConcurrent -XX:G1PeriodicGCInterval=10000 -XX:+UseStringDeduplication -XX:G1PeriodicGCSystemLoadThreshold=70
Running Stirling PDF with DOCKER_ENABLE_SECURITY=false and VERSION_TAG=0.46.2
Setting permissions and ownership for necessary directories...
Copying original files without overwriting existing files
running with JAVA_TOOL_OPTIONS -XX:+UnlockExperimentalVMOptions -XX:MaxRAMPercentage=75 -XX:InitiatingHeapOccupancyPercent=20 -XX:+G1PeriodicGCInvokesConcurrent -XX:G1PeriodicGCInterval=10000 -XX:+UseStringDeduplication -XX:G1PeriodicGCSystemLoadThreshold=70
Running Stirling PDF with DOCKER_ENABLE_SECURITY=false and VERSION_TAG=0.46.2
Setting permissions and ownership for necessary directories...
Additional Information
No response
Browsers Affected
No response
No Duplicate of the Issue
- [x] I have verified that there are no existing issues raised related to my problem.
Hi @joshmans! I'm Dosu and I’m helping the Stirling-PDF team.
Your logs show two main issues: (1) the container can't find or write to temp directories like /tmp, /var/tmp, or /usr/tmp, and (2) it can't find Tesseract OCR data files. Both are required for Stirling-PDF to start successfully.
Here’s what to check:
-
Temp directories: Make sure
/tmp,/var/tmp, and/usr/tmpexist and are writable inside the container. You can do this by runningdocker exec -it <container_name> ls -ld /tmp /var/tmp /usr/tmpanddocker exec -it <container_name> touch /tmp/testfile(and the same for the others). If these commands fail, it’s likely a permissions or mapping issue. -
Tesseract data: The error
cp: can't stat '/usr/share/tesseract-ocr/5/tessdata/*'means the container expects Tesseract language data at/usr/share/tesseract-ocr/5/tessdata/, but it’s missing. The official Docker docs show you should map your tessdata directory like this:-v ./StirlingPDF/trainingData:/usr/share/tessdataor, for extra OCR languages,
-v /location/of/trainingData:/usr/share/tessdata -
Container user: If you’re running the container as a custom user, try setting the user to
noneorroot. This has resolved similar permission issues for others source. -
Docker config: Double-check your Docker run or compose file matches the official example, especially the volume mappings for tessdata, configs, customFiles, logs, and pipeline.
If you’re still stuck, please share your Docker run/compose config and the output of ls -l for the temp and tessdata directories inside the container. This will help pinpoint the exact permissions or mapping problem.
To reply, just mention @dosu.
How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other 
![dosubot[bot] avatar](https://avatars.githubusercontent.com/in/324583?v=4 "Published by a pub.dev verified publisher"){kind=small}
@dosubot I am using @Frooodle 's docker template in the unraid community apps - there is no traditional docker compose here.
Thanks for clarifying you're using the Unraid Community Apps template. Here’s how to troubleshoot this in Unraid’s Docker UI:
Your logs show two main issues: (1) the container can’t find or write to temp directories like /tmp, /var/tmp, or /usr/tmp, and (2) it can’t find Tesseract OCR data files. Both are usually caused by volume mapping or permission problems in Unraid’s Docker setup.
First, in the Unraid Docker template editor, check that you haven’t accidentally mapped /tmp, /var/tmp, or /usr/tmp to a host path with restrictive permissions. If you have, try removing those mappings or ensure the host directories are world-writable.
Next, make sure you have a volume mapping for tessdata. The template should map a host folder (for example, trainingData) to /usr/share/tessdata inside the container. If this mapping is missing or points to an empty folder, you’ll get the Tesseract error. Example:
/mnt/user/appdata/stirlingpdf/trainingData (host) → /usr/share/tessdata (container)
Reference
Check the user settings in the template. If you have a custom user, PUID, or PGID set, try clearing those fields or setting the user to none or root—this has resolved similar permission issues for others reference.
Note: The DOCKER_ENABLE_SECURITY flag has been removed in recent versions. If you see it in your template, remove it or replace it with DISABLE_ADDITIONAL_FEATURES=true if needed reference.
If you’re still stuck, please share a screenshot or list of your Unraid template settings (especially volume mappings and user fields), and if possible, open a console in the running container and run:
ls -ld /tmp /var/tmp /usr/tmp
touch /tmp/testfile
This will help pinpoint if it’s a permissions or mapping issue.
To reply, just mention @dosu.
How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other
@dosubot The container does not run long enough to do any of those commands.
Here is a screenshot of my current template
I tried setting user in extra parameters of advanced to 99 (nobody), and it creates folders inside of appdata as user: root. I tried specifying the user using a name: nobody, root, and none... all with the same end results.
Based on your logs and config, the container is failing because it can't find or write to temp directories like /tmp, /var/tmp, or /usr/tmp, and it can't find the required tessdata files for OCR. Both are critical for startup and are usually caused by volume mapping or permissions issues in Unraid's Docker setup.
Here’s what to check and try next:
- Make sure you are not mapping
/tmp,/var/tmp, or/usr/tmpto any host path in your Unraid template. If you are, remove those mappings—mapping these can break temp directory handling in the container [source]. - For OCR to work, you must map a host directory (with only
.traineddatafiles inside) to/usr/share/tessdatain the container. If this mapping is missing or points to an empty folder, you’ll get the tessdata error [source]. - Remove any custom user or security parameters (like
DOCKER_ENABLE_SECURITYor user overrides) from the template. These are now deprecated and can cause permission mismatches [source]. - Check the permissions of your mapped host directories (especially for tessdata and configs) from the Unraid terminal. They should be world-writable or owned by
nobody:users(Unraid default). - If the above doesn’t help, try mapping a dedicated host directory (e.g.,
/mnt/user/appdata/stirlingpdf/tmp) to/tmp/stirling-pdfin the container to ensure a writable temp directory is available.
If you want, paste the text of your Unraid template settings (especially the volume mappings) here and I can help review for anything out of place.
To reply, just mention @dosu.
How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other
@dosubot
- I have no tmp or similar mappings in the template.
- the traineddata files appear to have populated into the OCR folder
- Security Params removed as advised
- I did map a tmp host directory and the exact same error occurred so I did remove the mapping again
Based on everything you've tried and the logs, this looks like an underlying Unraid Docker environment issue: the container can't see or write to standard temp directories, even with no mappings and correct permissions logic in the image. The Stirling-PDF Docker image and its scripts are designed to create and set permissions for /tmp/stirling-pdf and rely on the system's /tmp, /var/tmp, and /usr/tmp being present and writable. If these are missing or not writable—even for root—the container will fail to start, and this is almost always due to a host-level Docker overlay, permissions, or security setting on Unraid, not a bug in Stirling-PDF itself (details).
To isolate the problem, try launching a minimal container (like alpine or busybox) in Unraid with no volume mappings and run touch /tmp/testfile from the Unraid Docker console. If that fails, it confirms a broader Docker or Unraid config issue. Also, check if any Unraid plugins (like Docker Safe New Permissions or security plugins) are interfering with container filesystem access.
If you can, paste the exact text of your Unraid template's volume mappings and environment variables here (not a screenshot)—sometimes a subtle typo or extra mapping causes this. If the minimal container test fails, you may need to review your Unraid Docker settings or consult the Unraid community, as this is likely a host-level problem.
To reply, just mention @dosu.
How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other
@dosubot I have quite a few other containers, some I just loaded in today in fact that were able to utilize their /tmp directories just fine. All of these are containers maintained by inuxserver.io though, and they have built in UID/GID mapping support via environment variables.
For giggles I did install a random minimalist container (in this case 'minimal-ics-hoster') and ran 'touch /tmp/testfile.txt' within the container's console and I received no errors and also the file was created as expected.
Also @dosubot, here are my mappings in text format:
/usr/share/tessdata:/mnt/user/appdata/Stirling-PDF/OCR /configs:/mnt/user/appdata/Stirling-PDF/configs/ /customFiles:/mnt/user/appdata/Stirling-PDF/customFiles /logs:/mnt/user/appdata/Stirling-PDF/logs /pipeline:/mnt/user/appdata/Stirling-PDF/pipeline
@Froodle -
Network Type: Bridge Image: ghcr.io/stirling-tools/stirling-pdf:latest
I've tried enabling privileged to no avail as well.
I just had a thought - I'm using docker directory using the overlay2 storage driver (as opposed to a docker.img) as I've found that when I've used docker.img in the past I get corruption every few months. Could it maybe be related to this? I'm not sure how exactly but just a thought. I am running unraid 7.1.4.
That wasn't the GitHub image that came in the template, was there a reason for the change/anything else changed?
@Froodle - something to try to fix the problem. I also prefer ghcr.io based images as I've had the best luck with them pulling consistently.
Also changed the container path of the OCR to match the documentation when its regular docker compose: /usr/share/tessdata
I did set the image back to stirlingtools/stirling-pdf and get the same errors.
@Frooodle I added a post arg to sleep indefinitely so i could exec into the container. What user should own the directories and files? I wasn't expecting so many users:
/ # getent passwd root:x:0:0:root:/root:/bin/sh bin:x:1:1:bin:/bin:/sbin/nologin daemon:x:2:2:daemon:/sbin:/sbin/nologin lp:x:4:7:lp:/var/spool/lpd:/sbin/nologin sync:x:5:0:sync:/sbin:/bin/sync shutdown:x:6:0:shutdown:/sbin:/sbin/shutdown halt:x:7:0:halt:/sbin:/sbin/halt mail:x:8:12:mail:/var/mail:/sbin/nologin news:x:9:13:news:/usr/lib/news:/sbin/nologin uucp:x:10:14:uucp:/var/spool/uucppublic:/sbin/nologin cron:x:16:16:cron:/var/spool/cron:/sbin/nologin ftp:x:21:21::/var/lib/ftp:/sbin/nologin sshd:x:22:22:sshd:/dev/null:/sbin/nologin games:x:35:35:games:/usr/games:/sbin/nologin ntp:x:123:123:NTP:/var/empty:/sbin/nologin guest:x:405:100:guest:/dev/null:/sbin/nologin nobody:x:65534:65534:nobody:/:/sbin/nologin stirlingpdfuser:x:99:100::/home/stirlingpdfuser:/sbin/nologin
/ # ls -l total 94325 -rwxr-xr-x 1 stirlingpdfuser users 96406801 May 20 06:25 app.jar drwxr-xr-x 1 root root 4 May 20 06:26 bin drwxr-xr-x 1 stirlingpdfuser users 2 Jun 26 22:47 configs drwxr-xr-x 1 stirlingpdfuser users 2 Jun 26 22:47 customFiles drwxr-xr-x 14 root root 4880 Jun 28 13:45 dev drwxr-xr-x 1 root root 55 Jun 28 13:45 etc drwxr-xr-x 1 root root 3 May 20 06:26 home drwxr-xr-x 1 root root 17 May 20 06:26 lib drwxr-xr-x 2 root root 3 May 20 06:26 lib64 drwxr-xr-x 1 stirlingpdfuser users 2 Jun 26 23:05 logs drwxr-xr-x 5 root root 5 Feb 13 17:04 media drwxr-xr-x 2 root root 2 Feb 13 17:04 mnt drwxr-xr-x 1 root root 3 May 20 06:26 opt drwxr-xr-x 1 stirlingpdfuser users 2 Jun 26 23:05 pipeline dr-xr-xr-x 3119 root root 0 Jun 28 13:45 proc drwxr-xr-x 1 root root 2 Feb 13 17:04 root drwxr-xr-x 1 root root 3 Feb 13 17:04 run drwxr-xr-x 1 root root 9 May 20 06:26 sbin drwxr-xr-x 1 stirlingpdfuser users 13 May 20 05:53 scripts drwxr-xr-x 2 root root 2 Feb 13 17:04 srv dr-xr-xr-x 12 root root 0 Jun 28 13:45 sys drwxr-xr-x 2 root root 2 Feb 13 17:04 tmp drwxr-xr-x 1 root root 5 May 20 06:26 usr drwxr-xr-x 1 root root 3 Feb 13 17:04 var
If I try to manually chown it tells me operation not permitted. Are there any other commands I can run within the container that might be helpful? What about on my unraid host?
Interesting Development:
I had started the container with --user 99:100 in extra params and still had issues I then got rid of that, and still had the sleep infinity so i could exec - this time I could chown whatever I wanted to, but I wasn't sure what process i should take to try and force it.
I got rid of the sleep from post args and now we're back to not having a valid tmp and the container exits.
That wasn't the GitHub image that came in the template, was there a reason for the change/anything else changed?
I recently ran across a similar problem, the community applications stirling image defaults to the old image. I manually updated it and that fixed some of my problems, but could you update it for others?
Thanks for all you do!!!
