Why does a file watcher inside a Docker container miss host edits made over a bind mount?

## How a watcher actually learns about a change File watchers do not re-read your project every second — that is the fallback, not the design. They ask the kernel: `inotify_add_watch` registers interest in a directory or file, and the kernel queues events (`IN_MODIFY`, `IN_CREATE`, `IN_MOVED_TO`, ...) as operations happen through that filesystem. Everything about the container inner loop depends on those events surviving the trip from the editor on the host to the process inside the container. ## Cause one: the change never becomes an event on the container's side On a native Linux engine, a bind mount is not a copy or a sync — it is the same filesystem exposed at a second path. A write from your editor and a read from the container touch the same inode, so the kernel raises the event and the watcher sees it. Inner loops on Linux mostly just work. The failure mode appears when the engine is not on the same kernel as your editor. On a desktop engine the container runs inside a Linux virtual machine, and your project directory is shared into it by a file-sharing layer. That layer's job is to make the files *readable and writable*; making a host-side modification appear as an inotify event on the VM's filesystem is a separate problem, and implementations have historically not done it reliably or at all. The result is the classic report: the file content inside the container is right — `cat` shows the new line — but the watcher never fired. Nothing is corrupted; the notification simply never crossed the boundary. ## Cause two: atomic saves move the inode out from under the watch Many editors and build tools save safely: write `Program.cs.tmp`, `fsync`, then `rename()` it over `Program.cs`. The original inode is now unlinked and a *different* inode carries the name. A watcher that registered a watch on the file itself is still watching a file nobody will ever write to again, so the first save works and every later one is silent — or nothing is ever seen at all. Watching the containing directory instead picks up `IN_MOVED_TO` and behaves correctly; most mature watchers do this, which is why the symptom often looks like "only some tools miss changes". ## Cause three: you ran out of watches `fs.inotify.max_user_watches` caps how many watches a user may hold. It is a kernel sysctl on the host, not something a container can raise for itself, and Docker will not let you set it with `--sysctl` because it is not a namespaced parameter the daemon permits. A recursive watch over a large mounted tree — the whole repository including dependency and build-output directories — consumes one watch per directory and can exhaust the limit, after which registration fails with `ENOSPC` and the tool either logs an obscure error or silently degrades. Excluding dependency directories from the watch fixes more of these than raising the sysctl does. ## Diagnosing it quickly Run a trivial check inside the container against the mounted path: touch a file from the host and see whether a watch on the directory reports anything, then touch a file from a shell *inside* the container and see whether that one reports. If changes made inside the container raise events and changes made from the host do not, the boundary is the file-sharing layer, not your tool. If neither raises events, look at watch limits and at whether the tool is watching files rather than directories. ## The fixes, and what each costs * **Polling.** Every ecosystem has a switch: `CHOKIDAR_USEPOLLING=true` for the widely used JavaScript watcher, `DOTNET_USE_POLLING_FILE_WATCHER=true` for .NET tooling, and equivalents elsewhere. Polling asks the kernel nothing and stats files on an interval, so it is immune to the boundary problem. It costs CPU roughly in proportion to the number of files watched — noticeable on a large tree, especially inside a VM — and it adds up to one interval of latency before a reload begins. Tune the interval rather than accepting the default blindly. * **Watch less.** Mount only the directories you edit and exclude dependency and build-output trees. This cuts both inotify pressure and polling cost, and it is the fix that keeps paying. * **Remove the boundary.** Keep the repository on the same kernel the engine runs on — develop against a Linux engine, or hold the source inside the VM's own filesystem — and native events come back. ## Why this belongs in a senior conversation The symptom is deeply confusing: the mount works, the content is correct, the tool is configured properly, and nothing reloads. Candidates who can separate *file visibility* from *change notification* diagnose it in a minute; candidates who cannot will spend a day rewriting the Dockerfile. It is not a screening question — plenty of strong engineers have only ever run a Linux engine and never hit it — but the reasoning it exercises is exactly the reasoning that makes container debugging fast.