Why Does a Container Start Creating Root-Owned Files Only After an Image Update?

Eva Wong

IceWhale author

Eva Wong is the Technical Writer and resident tinkerer at ZimaSpace. A lifelong geek with a passion for homelabs and open-source software, she specializes in translating complex technical concepts into accessible, hands-on guides. Eva believes that self-hosting should be fun, not intimidating. Through her tutorials, she empowers the community to demystify hardware setups, from building their first NAS to mastering Docker containers.

Why Does a Container Start Creating Root-Owned Files Only After an Image Update?

A container may create root-owned files after an image update when the new image changes its runtime user, entrypoint, or startup ownership routine.

The persistent volume can remain unchanged while the replacement container starts under a different numeric UID or briefly runs an initialization step as root. A new entrypoint may create missing directories, migrate configuration, rewrite permissions, or stop honoring PUID and PGID variables used by the previous release. Compare one pre-update file, one startup-created file, and one file created by the running application before applying recursive ownership changes.

Prove That Ownership Changes Only After the Updated Container Starts

Stop the stack and record numeric UID, GID, mode, ACLs, and timestamps for one existing file and its parent directory. Start the updated container once with logs visible, then inspect the same path and one newly created file.

The Linux chown system calls change numeric ownership, so the decisive evidence is the UID and GID before and after startup rather than the username displayed by the host.

If ownership is already root before startup, the update is not the first cause. Investigate the update copy, extraction, backup restore, or administrator command that wrote the files.

Compare the Image User Before and After the Update

Inspect the old and new image configuration, effective container user, entrypoint, command, and release notes. Record whether the image now declares root, a named account, or a different numeric UID.

Docker documents that the USER instruction sets the runtime identity for later image instructions and for the container’s entrypoint and command when no runtime override replaces it.

An image can keep the same application username while changing its numeric UID. Compare numbers inside both image versions, because host-mounted files store numeric ownership rather than the image’s username label.

Check Whether the New Entrypoint Runs a Recursive Chown

Search startup logs, release notes, entrypoint scripts, and process traces for chown, permission repair, PUID, PGID, user migration, or directory initialization. Test on a small snapshot or disposable volume.

GNU Coreutils defines recursive chown as an ownership rewrite over the selected directory tree, which can make a correct existing volume appear to change immediately after the new image starts.

Do not remove the startup repair blindly. Some images rely on it for newly created directories. Prefer a documented skip flag, fixed application UID, or a narrower data path when the image supports one.

-15% OFF

ZimaBoard 2 - Mini Home Server for Your Big Idea

Single board computer zimaboard2

Audit Compose User Overrides and Removed PUID or PGID Variables

Compare the deployed Compose model before and after the update, including user:, environment variables, supplemental groups, profiles, override files, and the stack manager’s stored settings.

Kubernetes uses explicit numeric runtime and volume identities, illustrating the same container boundary: a runtime override and a volume ownership policy are separate settings that must remain aligned.

If the old image translated PUID and PGID variables but the new release removed or renamed them, the variables can remain present while no longer controlling the process. Verify the running UID directly.

Account for Rootless and User-Namespace ID Mapping

Record whether Docker runs rootful, rootless, or with user-namespace remapping. Compare the container-visible UID with the host-visible owner of the same inode.

Red Hat explains that rootless containers use subordinate UID and GID ranges, so container root does not necessarily appear as host UID 0 and an update can expose a changed mapping or runtime mode.

Do not recursively chown a rootless volume to host root without understanding the mapping. That can make the data inaccessible to the intended container identity.

Check Whether an Idmapped or Network Mount Changes the Visible Owner

Identify whether the app data is on a local filesystem, idmapped mount, NFS, SMB, FUSE, or NAS share. Record mount options and compare ownership from the server, host, and container.

The Linux kernel’s idmapped mount model separates filesystem ownership from mount ownership, so the same file can appear under different IDs without a physical recursive ownership rewrite.

If only the displayed owner changes after the update, verify whether the runtime now enters a different namespace or mount mapping. Repair the mapping rather than rewriting every inode.

Restore a Stable Runtime Identity and Verify the Next Update

Back up ownership metadata, stop the app, define the intended numeric UID and GID, correct only the app-owned paths, and redeploy with a pinned image and documented user settings.

The ZimaSpace article on container ownership after copying app data covers copy and migration causes; this article isolates a change introduced by the replacement image.

The repair is complete when startup, application writes, container recreation, host reboot, and a controlled image update all create files under the documented identity without broad permission exceptions.

Frequently Asked Questions

Does a root-owned file prove the whole container runs as root?

No. An entrypoint can run briefly as root to initialize a volume and then drop privileges before the application starts.

Should I recursively chown the entire volume?

Not before identifying the intended UID, shared paths, ACLs, and namespace mapping. A broad rewrite can break databases, shared media, or rootless-container ownership.