nas-tools/time_machine_troubleshooting.md

# Time Machine NAS Connection Troubleshooting

## Issue
Time Machine shows "Connecting to backup disk..." but never completes, even though:
- ✅ NAS is accessible from Finder
- ✅ User `zjgump` is in administrators group (has full permissions)
- ✅ Network connectivity is fine (ping works, SMB works in Finder)

## Root Cause Analysis

### Key Finding
**`zjgump` is in the administrators group** - This means:
- Explicit file permissions won't apply to SMB/file protocols
- Admin users have full access by default
- The "Permission denied" errors are NOT about file permissions

### Actual Issues
1. **Credential Cache Mismatch**: macOS has saved credentials for `DS224plus` (without .local) but Time Machine tries to use `DS224plus.local`
2. **Stale Mounts**: Manual mounts interfere with Time Machine's automatic mounting
3. **Time Machine Process Permissions**: Time Machine runs as a different user than your login user

## Solutions

### Solution 1: Clear Credentials and Let Time Machine Mount Itself (Recommended)

1. **Unmount all existing mounts:**
   ```bash
   diskutil unmount "/Volumes/Time Machine Folder" 2>/dev/null
   sudo umount -f /Volumes/.timemachine/* 2>/dev/null
   ```

2. **Clear saved credentials:**
   - Open **Keychain Access**
   - Search for `DS224plus`
   - Delete ALL entries related to DS224plus
   - Also search for `Time Machine` and delete related entries

3. **Remove Time Machine destination:**
   - System Settings → General → Time Machine
   - Remove the existing backup disk (click `-` button)

4. **Re-add Time Machine:**
   - Click "Add Backup Disk..."
   - Select "Time Machine Folder" on "DS224plus.local" (the one with `.local`)
   - When prompted, enter `zjgump` credentials
   - **Let Time Machine mount it itself** - don't mount it manually first

### Solution 2: Use a Dedicated Time Machine User (Best Practice)

Synology recommends using a **dedicated non-admin user** for Time Machine:

1. **On Synology DSM:**
   - Control Panel → User & Group → Create
   - Create user: `tm-backup` (or similar)
   - **Do NOT add to administrators group**
   - Set password

2. **Grant permissions:**
   - Control Panel → Shared Folder → Time Machine Folder → Edit → Permissions
   - Add `tm-backup` user with **Read/Write** permission
   - Check "Apply to this folder, sub-folders and files"

3. **Configure Time Machine on NAS:**
   - Control Panel → File Services → Time Machine
   - Select "Time Machine Folder" as the shared folder
   - Select `tm-backup` as the user (or leave blank for all users)

4. **On macOS:**
   - Remove existing Time Machine destination
   - Add Backup Disk → Select "Time Machine Folder – DS224plus.local"
   - When prompted, use `tm-backup` credentials (not `zjgump`)

### Solution 3: Fix Credential Cache for Admin User

If you want to keep using `zjgump` (admin user):

1. **Clear all DS224plus credentials:**
   ```bash
   security delete-internet-password -s "DS224plus" 2>/dev/null
   security delete-internet-password -s "DS224plus.local" 2>/dev/null
   ```

2. **Remove Time Machine destination**

3. **Manually connect via Finder first:**
   - Finder → ⌘K → `smb://DS224plus.local`
   - Connect as `zjgump`
   - This will save the credential properly

4. **Then add Time Machine:**
   - System Settings → Time Machine → Add Backup Disk
   - Select "Time Machine Folder – DS224plus.local"
   - It should use the saved credential

### Solution 4: Use IP Address Instead of Hostname

If Bonjour (.local) is causing issues:

1. **Find NAS IP:**
   ```bash
   ping -c 1 DS224plus.local | grep PING
   # Or check your router's DHCP table
   ```

2. **Connect via IP:**
   - System Settings → Time Machine → Add Backup Disk
   - If it doesn't show up, manually mount first:
     - Finder → ⌘K → `smb://192.168.1.172/Time Machine Folder`
     - Connect as `zjgump`
   - Then add the mounted share in Time Machine

## Diagnostic Commands

### Check Current Mounts
```bash
mount | grep -i "timemachine\|ds224plus"
```

### Check Time Machine Logs
```bash
log show --predicate 'subsystem == "com.apple.TimeMachine"' --last 10m --info | tail -50
```

### Check Saved Credentials
```bash
security find-internet-password -s "DS224plus"
security find-internet-password -s "DS224plus.local"
```

### Test SMB Connection
```bash
smbutil status DS224plus.local
```

### Check Time Machine Configuration
```bash
tmutil listbackups
defaults read /Library/Preferences/com.apple.TimeMachine
```

## Common Errors and Fixes

### "Time Machine could not back up the disk because it is nearly full"
- **Cause**: The **source disk** (Macintosh HD) is nearly full, NOT the destination (NAS)
- **Symptoms**: Error says disk is "nearly full" but NAS shows plenty of space (e.g., 1.67TB available)
- **Fix**: Free up space on your Mac's internal disk:
  1. Run the diagnostic script: `./free_disk_space.sh`
  2. Run the cleanup script: `./fix_time_machine_disk_full.sh`
  3. Or manually:
     - Empty Trash: `rm -rf ~/.Trash/*`
     - Clean caches: `rm -rf ~/Library/Caches/*`
     - Review Downloads folder (often has large files)
     - Use macOS Storage Management: Apple Menu → About This Mac → Storage → Manage
- **Why**: Time Machine needs free space on the source disk to:
  - Create local snapshots
  - Stage files for backup
  - Maintain the backup process
- **Minimum**: Aim for at least 5-10GB free space for Time Machine to work properly

### "Deleted files but space not freed" / "Stuck Time Machine snapshot"
- **Cause**: APFS snapshots (especially Time Machine local snapshots) hold onto deleted file space
- **Symptoms**: 
  - Deleted 20GB+ of files but disk space didn't increase
  - Error: "Stale NFS file handle" when trying to delete snapshots
  - `tmutil listlocalsnapshots /` shows snapshots that can't be deleted
- **Fix**:
  1. **Quick fix - Restart Mac**: Often the simplest solution - snapshots are released after restart
  2. **Remove Time Machine destination temporarily**:
     - System Settings → Time Machine → Remove backup disk
     - Delete snapshot: `sudo tmutil deletelocalsnapshots <date>`
     - Re-add Time Machine destination
  3. **Use the fix script**: `./fix_stuck_snapshot.sh` (guides you through the process)
  4. **Force purge**: `sudo purge` (if available)
- **Why**: Time Machine creates local snapshots before backing up. If the backup destination (NAS) is unreachable or has a stale connection, the snapshot gets stuck and holds onto space from deleted files.
- **Prevention**: Ensure Time Machine can reliably connect to backup destination

### "Permission denied" on mount point
- **Cause**: Manual mount with wrong permissions
- **Fix**: Unmount and let Time Machine mount it itself

### "Connecting to backup disk..." hangs
- **Cause**: Credential cache mismatch or stale mount
- **Fix**: Clear credentials, unmount all, re-add

### "Server may not exist or unavailable"
- **Cause**: Using wrong hostname (DS224plus vs DS224plus.local)
- **Fix**: Always use `.local` version or IP address

## Prevention

1. **Don't manually mount Time Machine shares** - let Time Machine do it
2. **Use dedicated non-admin user** for Time Machine (best practice)
3. **Keep credentials in sync** - if you change NAS password, update on Mac
4. **Use `.local` hostname** - more reliable than IP or NetBIOS name

## Notes

- Admin users (`zjgump`) bypass file-level permissions on Synology
- Time Machine runs as `_backup` user on macOS, not your login user
- Bonjour (`.local`) is preferred over NetBIOS for Time Machine
- Manual mounts can interfere with Time Machine's automatic mounting