Read mode, ACLs, and flags

Traditional owner, group, and mode bits are only part of file access. macOS also uses access control lists and file flags, and any of the three layers can be the one that blocks you. If you only look at rwx bits, you will fix the wrong layer.

Inspect one path and its parent

ls -ledO@ project project/config.json
stat -x project/config.json

ls -e shows ACL entries, -O shows flags, and -@ shows extended attributes. A typical result:

drwxr-xr-x@  8 flavio  staff  uchg 256 Aug  3 11:02 project
 0: group:everyone deny delete
-rw-r--r--   1 flavio  staff  -     412 Aug  3 11:02 project/config.json

Read it layer by layer. The + or @ after the mode string signals there is more than mode bits. Numbered lines like 0: group:everyone deny delete are ACL entries, evaluated before the classic bits — a single deny entry wins even when the mode looks permissive. The flags column (here uchg, the user immutable flag) can make a file read-only regardless of everything else.

stat -x confirms the numeric mode and exact ownership when the ls output is ambiguous.

Change only the proven layer

If an ACL denies the operation, edit the ACL (chmod -a removes an entry). If a flag locks the file, clear the flag (chflags nouchg project). If the mode is wrong, fix the mode. Change only the layer proven to block the intended process.

One flag deserves special respect: restricted marks paths protected by System Integrity Protection. You cannot clear it while SIP is on, and disabling SIP to “fix permissions” is never the answer. If a file is SIP-protected, macOS owns it, and the fix belongs elsewhere.

The mistake to avoid

Never start with recursive chmod 777. It rarely fixes ACL or flag problems, it destroys the permission record you needed as evidence, and it leaves world-writable files a later security review will flag. Diagnose first, then make the smallest change that unblocks the process.