v13 Breaking Changes and Fixes

[felddy]

This thread will help you quickly make the changes needed to migrate from the v12 version of this container to v13. Specifically it will address the causes of the failure logged in the lines below:

Entrypoint | 2025-04-19 18:35:53 | [error] Volume write test failed.
Entrypoint | 2025-04-19 18:35:53 | [error] Volume read test failed.
Entrypoint | 2025-04-19 18:35:53 | [error] Volume delete test failed.
Entrypoint | 2025-04-19 18:35:53 | [error] Aborting due to insufficient permissions on /data
Entrypoint | 2025-04-19 18:35:53 | [error] Container running as uid:gid: 1000:1000
Entrypoint | 2025-04-19 18:35:53 | [error] For more information see the discussion at: https://github.com/felddy/foundryvtt-docker/discussions/1197

What Changed in v13?

1. The container no longer executes as root. The default uid and gid are now 1000:1000.
2. Since the container does not have root permissions it can no longer change the permissions in the data volume to match the uid and gid of the server process. The CONTAINER_PRESERVE_OWNER environment variable that controlled this behavior is now deprecated.
3. FOUNDRY_UID and FOUNDRY_GID environment variables have been deprecated in favor of the native controls for the container's runtime. See below for more information.
4. The internal home directory has changed from /home/foundry to /home/node
5. The TIMEZONE environment variable has been replaced by the standard TZ environment variable.
6. linux/arm/v6 support has been dropped.

See the release notes for 13.341.0 for additional details and changes.

Resolving Permission Errors

You can either:

• make the data match the default process owner, or
• make the container process ownership match the existing data

Tip

Changing the ownership of the data is the easier of the two methods.

Changing the ownership of your /data directory

sudo chown -R 1000:1000 /path/to/your/data

Note

If you've moved the CONTAINER_CACHE directory outside of your data directory
you will need to reconcile the permissions of it as well.

Changing the user and group of the server process

Note

The container previously used uid:gid of 421:421.
If you didn't set your own custom ownership with v12 you should use 421 below.
If you previously set a custom uid and gid then use those same values with the new syntax.

Replace environment variables with runtime configurations.

Podman, Containerd, Docker

Compose files

v12 syntax:

environment:
  - FOUNDRY_UID=421
  - FOUNDRY_GID=421

v13 syntax:

user: 421:421

Command line

v12 syntax:

...  --env FOUNDRY_UID=421 --env FOUNDRY_GROUP=421

v13 syntax:

... --user 421:421

Kubernetes

v12 syntax:

env:
  - name: FOUNDRY_UID
    value: "421"
  - name: FOUNDRY_GID
    value: "421"

v13 syntax:

securityContext:
  runAsUser: 421
  runAsGroup: 421
  fsGroup: 421

---

Feel free to comment about your experience and any changes you think should be made to these instructions.

[felddy]

Link to an associated Reddit thread: https://www.reddit.com/r/FoundryVTT/comments/1kd41s1/anybody_else_struggling_to_get_version_13_up_and/

[johnpaul36]

i was using this container in unraid but now since the update its broken how do i fix the permissions

[felddy]

I don't use Unraid, but what I can gather from the Unraid documentation these should roughly be the steps:

1. Stop the Foundry container

   • In the Unraid Web UI, go to the Docker tab, find your FoundryVTT container and click Stop.

2. Open a shell on the Unraid host

   • SSH in as root:

   ssh root@<your-unraid-host>

   • Or click Terminal in the Unraid Web UI (top‑right) for a root shell.

3. Locate the host path of your data share
   Most likely under /mnt/user/appdata/....

   /mnt/user/appdata/foundryvtt

4. Chown the directory recursively

   chown -R 1000:1000 /mnt/user/appdata/foundryvtt

5. Verify ownership

   ls -ln /mnt/user/appdata/foundryvtt

   You should see both owner and group set to 1000:1000.

6. Restart the container

In the Docker tab, click Start on your FoundryVTT container.

If this isn't correct, I think you'd get more targeted help from the Unraid Docker FAQ forum.

[johnpaul36]

thanks so much this solved my issue

[BjornEinherji]

Holy hell thanks a lot for this! I was not aware of the changes in the new version so I kept blaming myself for screwing this up and kept troubleshooting. I changed permissions in my troubleshooting, but not the correct ones i see. Man glad that is over. Thank you for keeping this updated btw.

[Nicholaiii]

For other people using Unraid, set the UID and GID to 99 and 100. This is the default Unraid settings, and recommended to stay this way.

[iamq-dev]

I am unable to run sudo chown -R 1000:1000 /path/to/your/data. Where is the sudo password for the container defined?

[iamq-dev]

 chown -R 1000:1000 ./data
chown: changing ownership of './data/Backups2/modules/dnd-dungeon-masters-guide/module.dnd-dungeon-masters-guide.2025-01-26.1737929580097.bak': Operation not permitted
chown: changing ownership of './data/Backups2/modules/dnd-dungeon-masters-guide/module.dnd-dungeon-masters-guide.2025-01-26.1737929580097.json': Operation not permitted
chown: changing ownership of './data/Backups2/modules/dnd-dungeon-masters-guide': Operation not permitted
chown: changing ownership of './data/Backups2/modules/dnd-players-handbook/module.dnd-players-handbook.2025-01-26.1737917172819.bak': Operation not permitted
...

$ sudo 
/bin/sh: 11: sudo: not found

$ su
Password: 
su: Authentication failure

Running on windows server. docker backend is wsl. I have tried to chown in the wsl context but am still getting permission errors. I have also attempted to use windows permissions dialogs to give permissions to docker-users and even Everyone.

[felddy]

You should perform the permission changes on the host. The container does not have utilities for managing permissions or escalation of privileges.

[travisby]

Really appreciate the log line. I would have spent a lot longer debugging if not for that!

[aep]

same. thank you @felddy for the excellent work. this container is better maintained than some enterprise stuff.

[kunoichi6212]

I am hosting Foundry off my Synology. Am I able to do this using environment variables at all? If not how can I fix this so I can run 13?

[hidechron]

You have to go to "Project" in the sidebar, then "Create", then in the dropdown for "Source" select the second one.

(the fu, how many github account do I have >_<)

[TheodoreBrinkman]

I think the chmod 775 may have been the key. Once I did that the chown 1000:1000 worked.

[TheodoreBrinkman]

I've gotten it working thanks to the suggested chown command, but can you post a sanitized version of your .yml in case other people have issues in the future?

[voltcitron]

services:
  foundry:
    image: felddy/foundryvtt:latest
    user: "1041:100"
    hostname: myhostname
    restart: on-failure
    volumes:
      - ./data:/data
    environment:
      - FOUNDRY_PASSWORD=mypass
      - FOUNDRY_USERNAME=myusername
      - FOUNDRY_ADMIN_KEY=mykey
      - CONTAINER_PRESERVE_CONFIG=true
    ports:
      - target: 30000
        published: 30000
        protocol: tcp

[stetsonsdev]

So I was running into this issue as well. When you run "sudo chown -R 1000:1000 /path/to/your/data" be sure to use the specifc uid and gid in the chown command. So in my case I ran "sudo chown -R 1027:65536 /volume1/docker/foundry" then in the docker compose file include the "user:" line mentioned by voltcitron

[EvilRenegade]

@felddy I don't know how you (hard)coded those UIDs and GIDs, but on rootless Podman, the container utterly ignores all userns settings.

For others also running rootless Podman:
When you set up Podman, you also set up subuids and subgids for your executing user. Your volume/Foundry data should be owned by one of those subuids. Leave it like that.
To your previous command to run Foundry's container, add --uidmap=1000:421:1 --uidmap 0:0:1.
This should fix the permission mapping and allow you to start the container as before.

This works by assigning your user's intermediate uid 421 (your 421st subuid) on the host to uid 1000 in the container.
Since the container previously used uid 421 internally, this will come out to map the new container uid 1000 to the same host uid previously used in the host file system.

@felddy I acknowledge, respect and appreciate that an explanation and a link to this issue were logged by the container.
However, I would appreciate it if, next time around, instead of terminating the container in error, you could redirect to an explanatory page in the webserver, so that when the administrator tries to open Foundry, they instead get a warning and steps to fix.

Because those of us who are using your container because they're running Foundry headless on a server will have spent quite some time confusedly debugging the server before they see your message.

Not the least because you have consistently delivered a high quality product.
Your Foundry images have been running stable and reliable for years. I am very happy with them and I thank you for maintaining them.

It does mean that it's the last place I'm looking for a problem when the stack is failing, though.

If your image has always worked fine, and I just altered the stack to add a new cached installer, pull a new container image, update the process manager config to account for a new release tag, and then the container doesn't start, what is more likely: That I did everything right and your image just chooses not to run...or that I fucked up along the way?
Maybe the installer has the wrong filesystem permissions.
Maybe I didn't rename the ZIP properly.
Maybe there's a typo in the process manager config.
Maybe I swapped a digit in FOUNDRY_VERSION.

There are so many things I could've done wrong accidentally, that "maybe I did everything right and Foundry just doesn't want to run" isn't going to be high on the debugging checklist.

Sure, at some point, you get to the "this doesn't make sense...this should work...what does Podman say?" stage and see your message.

But adding a release notes vhost to the webserver and redirecting visitors if something's wrong gets your message to the reader a lot quicker...
Hell, you could even get fancy and just add a permanent /status endpoint, and just redirect to that on error.

Maybe something for the 13.345-version of the image? <_<

[Fraetor]

For running under rootless podman, I found that adding userns_mode: keep-id to my docker-compose.yml did the trick. This relies on your data directory also being owned by user 1000 on the host.

[EvilRenegade]

Not using compose, so it may be related to that.
Or to the fact that Debian doesn't like packages younger than the last ice age.

Either way, for me, uidmapping it to the previous user was what ultimately worked.

[Fraetor]

I did have to install podman-compose from bullseye-backports to get the feature.

[apastuszak]

How do I do this using a kubernetes yaml for Podman?

[Fraetor]

Update: After upgrading my host to Debian Trixie adding userns_mode failed with Error: --userns and --pod cannot be set together. This can be resolved by not running the containers in a pod by adding the following to your docker-compose.yaml file:

x-podman:
    in_pod: false

Documentation: https://github.com/containers/podman-compose/blob/main/docs/Extensions.md#custom-pods-management

[carleberg]

A detail left out: the container cache directory (and the .zip file itself) must also have their ownership changed. Meaning sudo chown -R 1000:1000 /path/to/your/container_cache.

Without it, you'll get an error saying: "CACHEDIR.TAG: permission denied". For me it was not enough to run chown on the data folder, I also had to do it on the folder where I store my installation .zip file. I was only able to solve this by tracking down the actual code for when this was changed: #1159, since the error message didn't actually tell what the error was.

[felddy]

Thank you for reporting this case. I've added a note above mentioning this situation.

[apastuszak]

OK, I cannot get the v13 container to start. I'm running it using rootless podman, and no matter what I do, I get this in my logs:

Entrypoint | 2025-07-12 21:12:05 | [info] Starting felddy/foundryvtt container v13.346.0
Entrypoint | 2025-07-12 21:12:05 | [error] Volume write test failed.
Entrypoint | 2025-07-12 21:12:05 | [error] Volume read test failed.
Entrypoint | 2025-07-12 21:12:05 | [error] Aborting due to insufficient permissions on /data
Entrypoint | 2025-07-12 21:12:06 | [error] Container running as uid:gid: 421:421
Entrypoint | 2025-07-12 21:12:06 | [error] For more information see the discussion at: https://github.com/felddy/foundryvtt-docker/discussions/1197

I'm using a Kubernetes YAML file and running podman play kube foundryvtt.yaml

My yaml file is:

---
apiVersion: v1
kind: Pod
metadata:
  name: Foundry_VTT
  labels:
    io.containers.autoupdate: registry
  annotations:
    # This tells Podman to create a user namespace where the host user's UID/GID
    # is mapped to UID 1000 and GID 1000 inside the container.
    io.podman.annotations.userns: "auto:uidmapping=0:0:1,uidmapping=421:1000:1"
spec:
  containers:
    - name: Foundry_VTT
      image: docker.io/felddy/foundryvtt
      env:
        - name: TZ
          value: "America/New_York"
        - name: FOUNDRY_USERNAME
          value: "XXXXXXXXXX"
        - name: FOUNDRY_PASSWORD
          value: "rEdAcTeD"
        - name: CONTAINER_PRESERVE_CONFIG
          value: "true"
        - name: FOUNDRY_ADMIN_KEY
          value: "ReDaCtEd"
      ports:
        - name: foundry
          containerPort: 30000
          hostPort: 30000
          protocol: TCP
      volumeMounts:
        - name: foundry_data
          mountPath: /data:z
  dnsPolicy: Default
  restartPolicy: Never
  SecurityContext:
    runAsUser: 421
    runAsGroup: 421
    fsGroup: 421

  volumes:
    - name: foundry_data
      hostPath:
        path: /home/andy/.podman/foundry_vtt/data

For the uidmapping, I've tried 421:1000:1 and 1000:421:1 and neither one works.

The data directory has owner:group set to 1000:1000. I'm running the pod as myself, which has a uid=1000,gid=1000

[EvilRenegade]

It's hard to determine after the fact, since you already got it working, but I believe the reason my solution didn't work for you was that you were going in the other direction:

• My solution assumes a state where the folder is owned by 421, and the container is newly running as 1000, so 1000 has to get remapped to 421.
• Your description here looks like your folder was owned by 1000, and you had reconfigured the container to run as 421. So you had a mismatch again.

The likely reason your solution from below worked is because your new config doesn't contain the security context, so now your folder owned by 1000 is getting accessed by the container newly running as 1000.
Where my solution aims to create the state described under "Changing the user and group of the server process" (data and container appearing as UID 421), you seem to have achieved the state described under "Changing the ownership of your /data directory" (data and container appearing as UID 1000).

You can check if your setup is sane by uploading something through Foundry (like a map or a token), and then checking if file ownership in the file system matches the other files.

[apastuszak]

Ok, I got it up! Here is what I did to fix it.

This is the yaml I used:

---
apiVersion: v1
kind: Pod
metadata:
  name: Foundry_VTT
  labels:
    io.containers.autoupdate: registry
spec:
  containers:
    - name: Foundry_VTT
      image: docker.io/felddy/foundryvtt
      env:
        - name: TZ
          value: "America/New_York"
        - name: FOUNDRY_USERNAME
          value: "XXXXXXXXXX"
        - name: FOUNDRY_PASSWORD
          value: "rEdAcTeD"
        - name: FOUNDRY_ADMIN_KEY
          value: "ReDaCtEd"
      ports:
        - name: foundry
          containerPort: 30000
          hostPort: 30000
          protocol: TCP
      volumeMounts:
        - name: foundry_data
          mountPath: /data:z
  dnsPolicy: Default
  restartPolicy: Never

  volumes:
    - name: foundry_data
      hostPath:
        path: /home/andy/.podman/foundry_vtt/data

I ran podman unshare chown -R 1000:1000 /home/andy/.podman/foundry_vtt

Then I ran podman play kube ./foundryvtt.yaml and it's up and running!

Please tell me if I did something wrong.

[Drazev]

I have resolved this change in a branch and placed a MR.

This was a result of two problems.

1. The ownership of the mounted volume and some files was still root, and not the non-root user created
2. The Docker-compose file from foundry-kanka re-creates the /data volume. This will replace any /data folder in the base image with a new version that belongs to the root user. It must be removed for the changes in my PR to work and it should be documented that users do not do this.

See #1241
and eXaminator/kanka-foundry#154

[Inch-high]

Anyone else managed to get this latest image working on Unraid, I've tried setting terms etc. However it just starts and then immediately stops, nothing showing up in the logs. I also noitced a bunch of deprecated variables seem to still be set on the unraid install, maybe this just needs some love?

[olterman]

I am also failing to get this up and running again I have changed permissions to 1000:1000 on the Data folder
sudo chown -R 1000:1000 *
I am running with podman compose up with the following docker-compose yaml

services:
  foundry:
    image: docker.io/felddy/foundryvtt:latest
    hostname: [redacted]
    init: true
    restart: "unless-stopped"
    volumes:
        - /home/self-hosted/FoundryVTT/Data:/data
    environment:
      - FOUNDRY_PASSWORD=[redacted]
      - FOUNDRY_USERNAME=[redacted]
      - FOUNDRY_ADMIN_KEY=[redacted]
      #- FOUNDRY_SSL_CERT=foundry.crt
      #- FOUNDRY_SSL_KEY=foundry.key
    ports:
      - target: 30000
        published: 30000
        protocol: tcp

I don't know what else to do

[Drazev]

Folks, as I discussed in #1241, one of the problems of this design with a non-root user is how Docker implements bind mounts. A bind mount is what you're doing each time you use the volume or bind feature to map a folder from the host filesystem into your container. This form of sharing between host and container was only intended for a container operating as root. You will need a more complex solution like those used in virtual machines to handle mapping users between the host and container systems. Docker has a guide on how to set this up for advanced users, so that you can manually identify the mappings between host users and container users. It is not easy to do for the average user.

Why?

Docker bind is lightweight compared to fusefs or other programs that act as a translation layer between the real filesystem and the filesystem's representation in a virtual machine. It was designed under the assumption that the container is running as the root user with the standard uid and gid of 0. In this scenario, the Linux kernel is shared between the host and containers does not need any translation at all. The Docker engine only needs to intercept links that would enable you to break out of your container. However, when you change the user in the container to a non-root user, then this all breaks down because the container is interpreting the filesystem data like the uid and gid of file owners based on the container's configuration. So you get things like permission problems because a file belongs to a uid and gid that doesn't exist in the container. It also means that if you run a command to change owners, it will update the file with a uid and gid that may not be assigned to the correct user in the host filesystem.

The Design Problem for this Container

This container assumes you can change the data folder to be owned by the user defined in the image. However, this doesn't work if you're substituting the data folder with a bind mount at run time (dockerr compose or docker run). When you create a container initially, any new bind mounts will overlay (hide) the folder previously at that mount point by replacing it with a new folder owned by the root user that acts as the entry point for that bind mount. This will break the scripts used in this image that are being run as the non-root user because they lack permissions. You must also be careful with changing permissions to your non-root user after startup, because it will change the owner in the host system by updating the owner uid or gid to a value that may be incorrect in the host system.

Solutions for Non-Root Container User

The safe solution that would consistently work for anyone would be to sync the user inside the container with a user in the host machine using the Docker method or another method. While other solutions do exist, they may have unwelcome and even dangerous side effects. Using this solution will limit the audience that can use this image securely. In most cases, people without sufficient knowledge would be encouraged to blindly follow any number of solutions that may work, potentially compromising their system security in the process.

My Recommendations

I suggest that this image return to use the root user. The non-root user setup has not added any extra security and encourages users to take actions that may compromise their host system security. The CVEs that involve users breaking out of the container into the host system all require some action in the host system that allows the container to get around the Docker protections to make this possible. A non-root user is ideal in situations where your container uses only volumes (not bind mount volumes) and can operate independently of the host system using only its own container resources or those in related images tied together by a container network or shared volumes.

Since this container requires the user to bind a data folder from the host machine for normal use, a non-root user doesn't make sense. The security of the container is now contingent on how the host system is configured, and that is beyond the control of a container designer. Even when it works, the level of security by adding a non-root user is at best the same as the root user. What you gain by attempting to create a hardened container, you lose with the extra complexity you have introduced. If at any point someone has access to the host machine, they can circumvent any container permissions just by how they create the container or through Docker engine commands that modify the image state without needing permission from the container operating system.

About Me

Take my advice as you will, because depending on your background, you may know more about some of these topics than me. For a bit of context, I work in the tech industry on secure operating systems. My role is integration with some R&D in nested virtualization and embedded system image building. This involves designing custom Linux and POSIX kernels and their related image filesystems. The virtualization research involves coordinating the resources of multiple layers of systems. One of my more recent solutions involved using Docker within my build process.

[dcpc007]

did you look about podman ?
more and more used in place of docker now.
And it has a base improvment logic of running non root

[Visteus]

Old thread, but I'm having the same issue now with trying to fresh-install v14 after a drive failure. I'm using Portainer + docker compose, and have set the /data mount to 1000:1000. Still getting Volume write test failed. Volume Read test failed.

Tried making a new user and assigning it all to them, tried rebinding the mount elsewhere, still nothing.