Troubleshooting

Helper needs approval or is not responding

Open DeltaSnap's assistant/settings and reinstall the helper if needed. Approve it under System Settings → General → Login Items & Extensions, then relaunch the app. The GUI, Finder features, and dsnap all depend on the same helper.

Use the helper-log shortcut in Settings or inspect:

/var/log/com.scaleninja.deltasnap.helper.log

The log self-rotates at 8 MB; one previous generation is kept beside it with a .previous suffix, and the complete record remains available in the unified log under the com.scaleninja.deltasnap.helper subsystem.

The background service seems stuck on an old version after an update

The app restarts the service itself when their versions differ, and asks again every minute or so until it takes; the service exits within about a minute even if it was busy. If the app posts DeltaSnap could not restart its background service, choose Assistant → Restart Helper, and failing that restart the Mac. The service that starts is always the one inside the updated app.

A "Background service is degraded" banner appears

The helper continuously checks its durable stores (schedules, protection holds, settings, history, audit log). When one degrades, the app shows a persistent banner naming the problem and a short reference code that also appears in the helper log.

While the protection or policy store is unhealthy, automatic snapshot deletion pauses as a safety measure: DeltaSnap will not prune when it cannot prove what is protected. Snapshot creation, indexing, and manual deletion continue. The banner clears on its own once the underlying condition (usually disk space or a damaged file under /var/db/com.scaleninja.DeltaSnap/) is resolved.

The notice is raised only after the condition has held for two minutes, so a blip at boot does not trigger it, and it turns into DeltaSnap helper recovered on its own when the condition clears; with email notifications on, both go out. Folders the system refuses to open, such as iCloud app containers inside a snapshot, are skipped and logged and do not count as degradation.

A volume or snapshot is missing

Confirm the disk is APFS, its Data volume is mounted, and DeltaSnap has Full Disk Access. Backup-role volumes are listed for reference, while system roles are filtered from normal management.

Version Control is not ready

Version Control requires one snapshot with a ready index, DeltaSnap's own or an external one. Create a snapshot, leave Settings → Indexing → Full scan enabled, and wait for indexing. To pull in external snapshots that already exist, compare two of them, use Index Snapshot on a row, or run Re-index Snapshots on the volume.

If a location says Not Indexed, review path/name exclusions. Use the Snapshots tab or Compare Everything when you need a one-off look inside an excluded tree.

The background service uses a lot of CPU

Versions before 1.0.1 re-measured every snapshot's cumulative size after each scheduled snapshot, which showed as a burst of CPU from com.scaleninja.deltasnap.helper every cadence and for minutes after a restart. Update to 1.0.2 or later.

On a very large volume, millions of files, each remaining measurement can still take seconds. Turn off Settings → Indexing → Measure snapshot sizes; the background service then does no size measurement at all. If CPU stays high with that off, check the helper log for snapshot sizes: and history: lines to see what is running. Indexing a new snapshot runs after each scheduled snapshot and takes minutes on a volume that size; Settings → Indexing controls whether and when it runs. If it still persists, run sudo sample com.scaleninja.DeltaSnap.Helper 30 -file ~/Desktop/deltasnap-helper.txt while it is happening and send us the file with the helper log.

A comparison is slow

The first comparison may build missing indexes. Proactive full-scan indexing runs in the background and can be disabled or deferred on battery. Compare Everything always walks both trees and is intentionally slower.

Finder menus or badges are missing

Enable DeltaSnap under System Settings → General → Login Items & Extensions → Added Extensions → Finder. Badges also require an indexed DeltaSnap snapshot on the volume. Finder can cache menus and badges; relaunch it if waiting does not refresh them.

A snapshot will not unmount

Close Finder, Quick Look, editors, and terminal directories using it. DeltaSnap deliberately keeps a mount while Version Control, search, or another window holds a lease.

Automatic snapshots do not run

• Confirm the schedule and at least one cadence are enabled for the exact volume.
• Confirm the helper is running and the volume is mounted/unlocked.
• Check the displayed next boundary and Activity log.
• Remember that boundaries missed during sleep are skipped.

A snapshot was pruned unexpectedly

Inspect its kind and Activity reason. Safety snapshots expire by global TTL; uncovered automatic snapshots use natural lifespans; count rotation applies to enabled cadences; low-space pruning can remove unprotected manual points. Protect any snapshot that must survive every automatic pruner.

Monitoring did not take a snapshot

Check Settings → Monitoring, watched paths, sensitivity, and Take safety snapshot on alarm. Excluded paths are ignored. Alarms are rate-limited per watched root and indicate unusually rapid changes, not every individual edit.

Email notifications are not arriving

Open Settings → Notifications and click Send Test Email; the result line repeats what the mail server said. Common causes, in order:

• Sign-in refused (535). Gmail and iCloud reject account passwords for SMTP; create an app-specific password and paste that instead. Microsoft 365 may need an administrator to allow SMTP AUTH for the mailbox.
• Timed out, or certificate error, on connect. The port and security mode do not match: use 465 with SSL/TLS, or 587 with STARTTLS. A relay with a self-signed certificate is refused on purpose; use a certificate the Mac trusts or a plain-text relay on a private network.
• The test works but nothing arrives later. Check that Send email notifications is on and that the scope covers the events you expect; critical-only skips pruning results and low-space warnings. The background service sends even when the app is closed, so the app does not need to be running. Also check the junk folder the first time.
• Fewer emails than events. That is the digest: routine items are grouped into one email per minute, and a condition that refreshes in place, such as low space, is not re-sent. See Notifications and email alerts.

After three failed deliveries in a row DeltaSnap posts Email notifications are not being delivered in the Notifications window, with the server's reply, and keeps retrying for about an hour and a half. The settings tab shows the last delivery problem and the time of the last successful send.

An AI agent cannot run dsnap

Verify dsnap version and dsnap list in your own Terminal first. If those work, allow the agent's sandbox to execute /usr/local/bin/dsnap and reach the local DeltaSnap helper. Restart the agent after installing the skill so it can refresh its skill catalog.

Exit 69 means the helper is unavailable or incompatible. Open DeltaSnap, approve or reinstall the helper, and retry. Exit 77 means the trial or license is not active; open DeltaSnap to resolve entitlement before asking the agent to continue.

License activation fails

Paste the complete DELTA-… key without whitespace, confirm network access, and retry under Settings → Licensing. Activation is the only step that needs a connection; once it succeeds the license is never rechecked. If the key is already registered to another Mac, deactivate it there first or contact support. If the Mac cannot reach the network at all, ask us for an offline license, which activates from a block of text with no connection.

dsnap is not found

Invoke /Applications/DeltaSnap.app/Contents/MacOS/dsnap directly. The helper creates /usr/local/bin/dsnap and /usr/local/bin/deltasnap only when it can do so safely; it will not overwrite a regular file or unrelated symlink.