Filesystem on Lessons learned

FSKit after mount -F: "ls: fts_read: Operation not permitted"

Sat, 26 Sep 2026 16:30:00 +0200

My new FSKit filesystem mounted without complaint, but nothing inside it could be read:

$ ls -la ~/mnt/storage-test
ls: fts_read: Operation not permitted
total 0
$ cat ~/mnt/storage-test/sub/a.txt
cat: /Users/me/mnt/storage-test/sub/a.txt: Operation not permitted

stat on the mount point worked. If your FSKit extension does the same after a mount -F from the command line, check its sandbox before your code: the extension can see the source folder’s metadata but may not read its contents.

The setup

macOS 26, a file system extension built on FSKit’s FSUnaryFileSystem that exposes a local folder through a mount point
A small host app, StorageHost.app, in /Applications; its executable runs mount -F -t storagefs <source> <mount point>
The extension StorageFS.appex with the FSKit entitlement and the app sandbox
Info.plist with FSSupportsPathURLs set to true and FSRequiresSecurityScopedPathURLResources set to false

What went wrong

The first mount was over ~/Downloads, so the obvious suspect was privacy protection (TCC) for that folder. A fresh ~/storage-test with one file in it failed the same way, which ruled TCC out and pushed the search elsewhere.

My coding agent’s first log queries came back empty, and it told me there were no log entries. That was wrong. In zsh, log is a builtin, so log show ... 2>/dev/null runs the builtin, sends its too many arguments error to /dev/null, and prints nothing. Call /usr/bin/log by its full path. With that, the kernel had the answer:

kernel (Sandbox) 3 duplicate reports for Sandbox: StorageFS(83505) deny(1) file-read-data /Users/me/storage-test

The extension’s own log showed the failures from FSKit’s side: readDirectory:...reply:error:1 and readFrom:...reply:error:1. Error 1 is EPERM, which ls turns into fts_read: Operation not permitted.

Fix

mount -F gives the extension a plain path, not a security-scoped URL, so a sandboxed process can’t read an arbitrary path. For development, grant temporary sandbox exceptions in the extension’s .entitlements file:

<key>com.apple.security.temporary-exception.files.home-relative-path.read-write</key>
<array>
	<string>/</string>
</array>
<key>com.apple.security.temporary-exception.files.absolute-path.read-write</key>
<array>
	<string>/Volumes/</string>
</array>

This covers your home folder and external drives. It doesn’t override privacy protection, so ~/Downloads, ~/Documents, and ~/Desktop may still be refused; test with a folder elsewhere. Temporary exceptions are for development on your own machine. A shipping extension should use security-scoped resources instead. FSRequiresSecurityScopedPathURLResources in Info.plist requests that; I haven’t managed a clean test yet (see below).

The same logs flagged two more problems that I fixed along the way:

-[FSModuleVolume(Project) getMaxFileSizeInBits]: Volume implements neither maxFileSizeInBits nor maxFileSize. One of them must be implemented.
-[FSVolumeConnector getStandardItemAttributesForItem:replyHandler:]_block_invoke: Reported attributes are incomplete

The first needs maximumFileSizeInBits on the volume. The second went away once the item attributes set flags, which cleared the log entry.

Reinstalling switches the module off

To test each change, I replaced the app: rm -rf /Applications/StorageHost.app, copied the new build, and launched it once. After that, mount failed outright:

Module com.example.storage.fs is disabled!
mount: Unable to invoke task

pluginkit disagreed. pluginkit -e use -i com.example.storage.fs succeeded, and pluginkit -m listed the extension with a +, which means enabled. FSKit still refused. It keeps its own switch in System Settings → General → Login Items & Extensions → File System Extensions, and I didn’t find a command-line way to flip it. After I turned StorageFS back on there, the next mount listed and read files, and appends, renames, truncation, and an 8 MB write-and-readback all worked.

The disabled module also spoiled my one test of security-scoped resources. With FSRequiresSecurityScopedPathURLResources set to true, mount failed with Unable to invoke task, but the reinstall had just switched the module off, so the failure says nothing about the setting.

Why

An FSKit module is an app extension, and FSKit requires it to run in the app sandbox. When an app hands a folder to the extension, sandbox access can travel with it as a security-scoped URL. mount -F on the command line passes only a string. The sandbox lets the extension look up metadata for that path, which is why the mount and stat worked, and denies file-read-data, which every directory listing and file read needs.

Takeaway

If an FSKit mount works and every read returns Operation not permitted, search the kernel log for deny(1) file-read-data with /usr/bin/log, then give the extension sandbox access to the source path. After every reinstall, check the File System Extensions switch before you trust a test result.

If you’ve got FSRequiresSecurityScopedPathURLResources working with a command-line mount -F, I’d like to hear how.

Tilde pointed at a profile home, so the export landed elsewhere

Mon, 04 May 2026 00:00:00 +0000

The export command finished, but the expected directory was empty. Then Python reported [Errno 2] No such file or directory for a script that existed in the user’s home. The runner’s HOME pointed at a profile-specific directory. Fixing this required explicit paths for both the export destination and the Python environment.

Two homes, two plausible directory trees

An initial attempt to read a helper resolved to a profile-home path where the file did not exist. During the later export, cd ~/transfer succeeded because that directory existed too. A virtual environment had been created there, but the actual transfer script lived under the user’s expected home.

The terminal output settled the discrepancy: printing HOME returned the profile-specific home. Comparing the two transfer directories found the script only under the expected user-home root. Comparing output directories found exported data under that root and an empty directory under the profile home. The report also existed only under the expected root.

Changing directories alone would still leave Python’s Path("~/data").expanduser() following the process’s HOME. The repair replaced tilde-based output defaults with explicit absolute destinations, including separate report and log paths. The script supported overrides such as KB_OUT_ROOT. Running it from the intended transfer directory also selected that directory’s .venv/bin/python.

This was observed in a historical Hermes runner environment. It does not establish that every Hermes profile changes HOME; consult the current Hermes documentation for your setup. A configured profile directory and the home directory you expect are separate facts to check.

Check the process before searching for files

Run these inside the same terminal tool or wrapper that launches the job:

printf 'HOME=%s\n' "$HOME"
id
pwd
python3 -c 'import sys; from pathlib import Path; print(sys.executable); print(Path.home())'

Compare those paths with the expected project root. Limit directory checks to those known roots; a filesystem-wide search adds noise and can expose unrelated private files. A successful cd proves only that a directory exists, not that it contains the intended script or environment.

Shell expansion happens before the child starts

In Bash, unquoted ~/data expands in the calling shell. In env HOME=/somewhere python3 ... ~/data, the argument has already expanded before env changes the child’s environment. Single-quoted '~/data' stays literal; Python must expand it explicitly. On Unix, Path.expanduser() uses HOME when it is set.

This isolated example demonstrates both cases without touching real home directories:

SCRATCH="${TMPDIR:?Set TMPDIR to your scratch directory}/home-path-demo"
mkdir -p "$SCRATCH/caller-home" "$SCRATCH/profile-home"
PYTHON="$(command -v python3)"
export SCRATCH PYTHON
HOME="$SCRATCH/caller-home" bash --noprofile --norc <<'SH'
env HOME="$SCRATCH/profile-home" "$PYTHON" -c \
 'import sys; print(sys.argv[1])' ~/data
env HOME="$SCRATCH/profile-home" "$PYTHON" -c \
 'import sys; from pathlib import Path; print(sys.argv[1]); print(Path(sys.argv[1]).expanduser())' '~/data'
SH

The first command prints the caller’s home path. The second prints the literal ~/data, then the profile-home path.

Pin the interpreter and verify the artifact

Here is a standalone local inventory example. The program reads its input directory as read-only; the output root is explicit. It requires Python’s venv module and uses only scratch fixtures.

SCRATCH="${TMPDIR:?Set TMPDIR to your scratch directory}/home-path-demo"
mkdir -p "$SCRATCH/source" "$SCRATCH/exports"
printf 'fixture\n' > "$SCRATCH/source/sample.txt"
python3 -m venv --without-pip "$SCRATCH/venv"
export DATA_ROOT="$SCRATCH/source" KB_OUT_ROOT="$SCRATCH/exports"
"$SCRATCH/venv/bin/python" <<'PY'
import os
import sys
from pathlib import Path

source = Path(os.environ["DATA_ROOT"])
out = Path(os.environ["KB_OUT_ROOT"])
if not source.is_absolute() or not out.is_absolute():
 raise ValueError("Use absolute input and output roots")
artifact = out / "inventory.txt"
artifact.write_text("\n".join(sorted(p.name for p in source.glob("*.txt"))) + "\n")
assert artifact.read_text() == "sample.txt\n"
print("interpreter:", sys.executable)
print("verified artifact:", artifact.resolve())
PY

For a real export, validate expected contents at the selected destination and check the report there. In the failed run, a pipeline ending in tail returned zero even though Python could not open the script. Command status alone missed both the launch failure and the path mismatch. Check your job’s resolved interpreter and output root before its next run.