Back to Resources
Filesystem Diagnostics for macOS FSEvents, Linux inotify, and Skill SyncLast Updated: Published November 22, 2026

How to Fix EACCES Permission Denied Errors in AI Agent File Watchers

To fix an AI agent file watcher EACCES error, restore user ownership on root-polluted skill directories (~/.claude/skills, ~/.codex/skills, ~/.gemini/config/skills), grant macOS sandbox read access, or resolve Docker bind-mount UID mismatches. If the watcher actually fails with ENOSPC or EMFILE, raise Linux fs.inotify.max_user_watches to 524288 and exclude node_modules.

macOS FSEvents
Linux inotify
Cross-Agent Sync

Agent skill edits not reloading due to EACCES, ENOSPC, or EMFILE watcher crashes? Fix macOS FSEvents, Linux inotify, and Docker bind-mount permissions.

To fix an AI agent file watcher EACCES error, restore user ownership on root-polluted skill directories (~/.claude/skills, ~/.codex/skills, ~/.gemini/config/skills), grant macOS sandbox read access, or fix Docker bind-mount UID mismatches. If the watcher crashes with ENOSPC or EMFILE instead, raise Linux fs.inotify.max_user_watches to 524288 and exclude dependency trees.

Symptom-to-Cause Matrix: EACCES vs. ENOSPC vs. EMFILE in Agent Watchers

Separating true EACCES permission denials from kernel watch-table limits (ENOSPC) and file-descriptor exhaustion (EMFILE) prevents wasted sysctl edits when the real blocker is a root-owned SKILL.md folder. Many Node.js and Rust watcher wrappers surface generic permission or initialization errors whenever a single unreadable directory sits inside a recursive watch tree across Cursor, Claude Code, OpenAI Codex CLI, or Google Antigravity.

As documented in the official Node.js File System fs.watch documentation:

"On Linux systems, this uses inotify(7). On BSD systems, this uses kqueue(2). On macOS, this uses kqueue(2) for files and FSEvents for directories."

Because the underlying kernel subsystem differs by OS, use this triage matrix to match your exact error code to its verified remediation:

Kernel ErrorUnderlying TriggerAI Agent Watcher SymptomVerified Fix
EACCESRoot-owned ~/.claude or ~/.codex folder, missing +x dir bit, or macOS TCC denialWatcher crashes at launch or silently drops SKILL.md editsRun chown -R $(id -u):$(id -g) and grant Full Disk Access
EPERMmacOS SIP protection or immutable chflags uchg lock on skill pathOperation not permitted when traversing protected foldersRelocate skills to ~/.claude/skills and run chflags nouchg
ENOSPCLinux inotify watch table exhausted across node_modules or .venvCursor or Codex aborts with file watcher limit reachedSet fs.inotify.max_user_watches=524288 and exclude build dirs
EMFILEmacOS 256 soft maxfiles cap or Linux max_user_instances exhaustedToo many open files when multiple coding agents run togetherExclude .git/objects and raise ulimit -n / max_user_instances

Why Do macOS Sandboxing and Root-Owned Dotfiles Trigger EACCES in Agent Watchers?

On macOS, AI agent file watchers fail with EACCES when a prior sudo install creates root-owned folders under ~/.claude/, ~/.codex/, or ~/.gemini/, or when macOS TCC blocks a sandboxed process. macOS also enforces a 256-descriptor soft limit (via launchctl limit maxfiles), causing kqueue(2) watchers to hit EMFILE alongside .cursor/rules/*.mdc trees.

  1. Root-Owned Config Directories: Running sudo npm install -g leaves ~/.claude/skills or ~/.codex/skills owned by root:wheel at 0700, locking out user-space sync daemons.
  2. Missing Directory Execute Bits (+x): Archives or SMB copies can strip directories to 0644; traversing a folder to register an FSEvents or kqueue watch requires 0755.
  3. macOS TCC Sandbox Denials: Background launchd agents or IDEs watching ~/Documents or ~/Desktop hit TCC EACCES blocks without Full Disk Access.
# Inspect ownership and restore user permissions on macOS skill directories
ls -ld ~/.claude/skills ~/.codex/skills ~/.gemini/config/skills
sudo chown -R "$(id -u):$(id -g)" ~/.claude ~/.codex ~/.gemini ~/.agents 2>/dev/null || true
find ~/.claude/skills ~/.codex/skills ~/.gemini/config/skills -type d -exec chmod 755 {} + 2>/dev/null || true
launchctl limit maxfiles && ulimit -n 65536

How Do You Fix Linux inotify EACCES, ENOSPC, and Docker Bind-Mount Failures?

On Linux devboxes and remote SSH hosts, fixing file watcher failures requires matching the exact kernel error returned by inotify: repair UID ownership and mode bits for EACCES, or increase kernel watch limits for ENOSPC and EMFILE. When mounting host skill folders into Docker dev containers for Google Antigravity, Cursor, or Codex CLI, a host-vs-container UID mismatch frequently leaves /home/node/.gemini/config/skills owned by UID 0 or UID 1000, causing the container watcher to fail immediately.

The Linux inotify_add_watch(2) manual page defines the two primary watch-registration failures explicitly: EACCES means "Read access to the given file is not permitted," whereas ENOSPC means "The user limit on the total number of inotify watches was reached or the kernel failed to allocate a needed resource." Similarly, the inotify_init(2) manual page defines EMFILE as "The user limit on the total number of inotify instances has been reached."

For Linux workstations hitting ENOSPC while Cursor, Claude Code, and local sync daemons watch large repositories simultaneously, the official Visual Studio Code Linux setup documentation recommends raising fs.inotify.max_user_watches to 524288. Apply the persistent sysctl and permission repair below:

# 1. Check current Linux inotify limits and active watch consumers
cat /proc/sys/fs/inotify/max_user_watches /proc/sys/fs/inotify/max_user_instances
lsof +c 0 | awk '/inotify/{print $1}' | sort | uniq -c | sort -nr | head -n 10

# 2. Persist higher inotify watch and instance limits (survives reboot)
echo "fs.inotify.max_user_watches=524288" | sudo tee /etc/sysctl.d/99-ai-agent-watchers.conf
echo "fs.inotify.max_user_instances=1024" | sudo tee -a /etc/sysctl.d/99-ai-agent-watchers.conf
sudo sysctl --system

# 3. Fix Docker / devcontainer UID mismatch on mounted skill directories
sudo chown -R "$(id -u):$(id -g)" "$HOME/.claude/skills" "$HOME/.codex/skills" "$HOME/.gemini/config/skills"

The Sprawl Moment: When a Broken File Watcher Silently Freezes Skill Updates

A silent file watcher permission failure leaves your editor, terminal agent, and remote devbox running contradictory versions of the same skill without warning. You refine a PostgreSQL migration-safety SKILL.md inside your central dotfiles repository on Monday morning, assuming your custom background file-sync script mirrors every edit across your Cursor workspace, Claude Code, and your Linux SSH devbox. Two days later, a teammate ships a breaking column alteration because the Linux container's inotify watcher crashed silently with EACCES on a root-owned subdirectory and stopped propagating skill updates across tools. Because no error surfaced in your terminal prompt, your local Mac, your Cursor .cursor/rules, and your remote OpenAI Codex CLI session quietly diverged into three incompatible versions of the same safety check.

Prompttly is a skill manager for AI agents — one library for your skills and prompts that syncs into Claude Code, Codex, ChatGPT, and Claude and is one hotkey away on your Mac, so your setup follows you across every machine, repo, and tool. Instead of maintaining brittle inotify scripts or debugging broken POSIX symlinks across ~/.claude/skills and ~/.codex/skills, Prompttly handles native two-way sync on macOS with sub-200ms hotkey insertion across every editor and web chat.

What Should Be Excluded From Agent File Watchers to Prevent Descriptor Exhaustion?

Preventing EMFILE and ENOSPC watcher crashes requires excluding build caches, package directories, and immutable Git object trees before raising OS kernel limits. Watching raw repository roots without exclusions wastes tens of thousands of kernel descriptors on node_modules, Python .venv environments, and .git/objects, crowding out actual instruction files like SKILL.md, AGENTS.md, and .cursor/rules/*.mdc.

Configure your IDE and custom sync scripts to watch only skill and rule manifests while ignoring heavy dependency paths:

// .vscode/settings.json or Cursor workspace settings — keep watchers off dependency trees
{
  "files.watcherExclude": {
    "**/.git/objects/**": true,
    "**/.git/subtree-cache/**": true,
    "**/node_modules/**": true,
    "**/.venv/**": true,
    "**/dist/**": true,
    "**/.next/**": true
  }
}

If you are troubleshooting a related symlink breakage or cross-OS permission strip, check our guides on debugging broken AI skill symlinks and ELOOP traps, moving AI agent skills across macOS, Linux, and Windows, and syncing Google Antigravity skills over SSH and Docker devboxes.

Frequently Asked Questions: AI Agent File Watcher EACCES Errors

Why does an AI agent file watcher throw EACCES on macOS or Linux?

An AI agent file watcher throws EACCES when it lacks POSIX read or directory-execute permissions on ~/.claude/skills, ~/.codex/skills, or ~/.gemini/config/skills. Common causes are sudo CLI installs, root-owned Docker bind mounts, or macOS TCC sandbox blocks.

What is the difference between EACCES and ENOSPC in Linux file watchers?

According to inotify_add_watch(2), EACCES means read access is not permitted, whereas ENOSPC means the user limit on total inotify watches was reached. Fix EACCES with chown/chmod, and fix ENOSPC by raising fs.inotify.max_user_watches to 524288.

How do macOS FSEvents and Linux inotify differ for coding agent watchers?

Linux watchers rely on inotify(7), which registers one kernel watch per directory and fails with ENOSPC in large dependency trees. macOS uses FSEvents for directories and kqueue(2) for files, hitting TCC EACCES denials or the 256-descriptor soft maxfiles limit instead.

Explore more cross-agent troubleshooting and skill architecture guides on the Prompttly Resources Hub, or build clean, spec-compliant manifests with the free Claude Skill Creator.

Replace brittle file watcher scripts with native two-way skill sync

Prompttly keeps your skills and prompts synchronized across Claude Code, Codex CLI, Cursor, and ChatGPT without recursive bash watchers, dangling symlinks, or EACCES permission traps—backed by a sub-200ms Mac hotkey palette.