apple / apple/container

[Bug]: A file mount nested inside a directory mount replaces the parent share (directory mounts unaffected)

Open
#2,148 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Swift
Stars
49.9k
Forks
1.8k
Avg merge
1d 20h
Merged PRs (30d)
22

Description

### I have done the following

- [x] I have searched the existing issues
- [ ] If possible, I've reproduced the issue using the 'main' branch of this project

(Reproduced on the 1.2.2 release binary, not a `main` build.)

### Steps to reproduce

Mounting a **file** at a path nested inside a directory mount causes the parent
directory mount to be **replaced** rather than overlaid — every other file in the
parent share disappears from the container.

```sh
mkdir -p /tmp/sess /tmp/group/subdir
echo PARENT-SHARE-CONTENT > /tmp/group/marker.txt
echo '{"nested":true}' > /tmp/group/config.json
echo sub > /tmp/group/subdir/inner.txt

# CONTROL — parent share only
container run --rm \
-v /tmp/sess:/workspace \
-v /tmp/group:/workspace/agent \
docker.io/library/alpine:latest ls -1 /workspace/agent

# TEST — identical, plus one nested FILE mount
container run --rm \
-v /tmp/sess:/workspace \
-v /tmp/group:/workspace/agent \
-v /tmp/group/config.json:/workspace/agent/config.json:ro \
docker.io/library/alpine:latest ls -1 /workspace/agent
```

### Actual behavior

```
CONTROL: TEST:
config.json config.json
marker.txt
subdir
```

`marker.txt` and `subdir/` are gone. The parent share has been replaced by the
single nested file.

### Expected behavior

The nested file mount overlays that one path; the rest of the parent share stays
visible. Docker's behavior on the identical three mounts (verified locally):

```
config.json
marker.txt
subdir
```

### Boundary conditions

| Variant | Result |
|---|---|
| Nested **file** mount, `:ro` | **Parent share replaced** |
| Nested **file** mount, read-write | **Parent share replaced** (so `:ro` is not the trigger) |
| Nested **directory** mount | Correct — all entries present |
| Same three mounts under Docker | Correct — all entries present |

So this is specific to *file* mounts nested inside a directory mount, in either
access mode.

### Why this is easy to miss

We hit this in production and did not notice for weeks. The symptom is silent:
the mount that *does* survive is the nested file, which is usually the file you
were actively looking at — so spot-checks pass. What disappears is everything
else in the parent directory. In our case a per-session config file mounted
read-only inside an agent's workspace collapsed that entire workspace to the
single config file, across every container on the host. No error, no warning,
and the surviving file made it look healthy.

A warning at mount-resolution time when a file mount shadows an enclosing
directory mount would have caught this immediately.

### Environment

- `container` CLI **1.2.2** (release)
- macOS 26 (Darwin 25.1.0), Apple Silicon (Mac16,9)

Contributor guide

Open the contributing guide

Research direction

Run the control and test mount commands from the issue with the container 1.2.2 setup, then trace mount resolution for a nested file mount inside a directory mount. Compare the resulting directory contents with Docker and verify that the parent entries remain visible while the nested file is overlaid in both read-only and read-write modes.

Written by the indexing model from the issue text.

Assessment

Tech stack
swift
Domain
cli, infrastructure
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
62/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.