Troubleshooting & common issues

Diagnostic flow

When something breaks, walk this in order. 90% of issues fall out by step 4.

1. Reproduce. Can you trigger the issue intentionally? If it was a one-off, note timing & conditions but move on.
2. Check the obvious. Disk full? macOS version current? SecVF version current?
3. Read the audit log. tail -50 ~/.avf/logs/error-audit.log — the typed error is often diagnostic on its own.
4. Read the security log. tail -100 ~/.avf/logs/security-$(date +%F).log — WARNING and CRITICAL entries near the failure time.
5. Check Console.app. Filter by process SecVF. Look for crash reports and OS-level errors the app may not have caught.
6. Check the guest. If the guest can boot at all: journalctl -xe inside it.

Where logs live

VM won't start / boot

"Start" button does nothing

Open error-audit.log — there's almost certainly a typed error with category: "vm-start". Common subtypes:

• missing-disk-image — bundle is corrupt or moved. Restore from snapshot, or recreate.
• insufficient-memory — host doesn't have enough free RAM. Close other apps; reduce VM RAM in config.
• entitlement-denied — running from an unsigned build. Re-sign per Installation.

VM boots to a black screen

The framework started, the guest is running, but you see nothing.

• Click inside the VM window once — sometimes the display device needs a "wake" event.
• For Linux guests, check if the boot got past GRUB — press Enter to pick a kernel.
• If the cursor is just blinking: the guest is at a TTY login but the framebuffer didn't initialize. Try Ctrl+Alt+F2 to switch TTYs.
• For macOS guests, a black screen for >30 s usually means the guest panicked. Force-stop, snapshot the bundle, file a report.

VM starts but can't boot the OS

"No bootable device" in the firmware screen.

• Is the install ISO still attached? After OS install you must eject the ISO before the guest can boot from its disk.
• Check NVRAM file in the bundle exists and is non-zero. If empty, the install never wrote a boot entry.
• Recreate the VM and re-install the OS. Disk images are sparse — the old disk file might be salvageable.

VM hangs at "Booting…"

• Give it 60 seconds — the first boot after install can take that long while the OS initializes.
• Force-stop, restart. Some guests don't recover well from a paused → resumed transition on the first boot.
• If repeatable: capture the audit log + an Activity Monitor screenshot showing the SecVF process and file an issue.

Network issues

Guest can't reach the internet (NAT mode)

• Inside guest: ip addr show — interface should have an IP (Apple's NAT gives DHCP).
• ping 1.1.1.1 from inside the guest. If that works but ping google.com doesn't, it's DNS — check resolv.conf.
• Check the host's firewall (System Settings → Network → Firewall). Some configurations block VM network attachments.

VMs can't see each other on the virtual switch

• Open Monitoring → Switch Statistics (⌘⇧3). Both VMs should show in the MAC table.
• If only one shows: the other isn't actually attached. Check its network mode — VM Library → right-click → Edit configuration → Network mode.
• Verify the VMs are in the same mode. "Virtual" and "Router" are different networks; they only intersect via the router VM as gateway.

Router VM mode: lab guests get DHCP but no internet

• SSH into the Kali router. secvf-status — IP forwarding should be enabled.
• sudo sysctl net.ipv4.ip_forward should return 1. If 0, the router setup script didn't run or sysctl was reset.
• sudo iptables -t nat -L POSTROUTING -v — MASQUERADE rule on eth1 must be present.

Packet capture issues

"Start capture" is disabled

• tshark not installed: brew install wireshark, then restart SecVF.
• tshark installed but not on PATH: which tshark. If empty, your shell's PATH isn't seeing it. Common cause: /opt/homebrew/bin not in PATH for GUI apps (only for terminal sessions). Add it via launchctl setenv PATH "$PATH" or use the App Store path that uses libpcap.

Capture starts but no packets show up

• The selected VM isn't generating traffic — try ping 1.1.1.1 from inside.
• Wrong interface — set the interface dropdown to any switch traffic.
• BPF prefilter is too aggressive — clear it and retry.

Capture drops packets under load

• Switch Statistics shows non-zero Packets Dropped. The capture queue is saturating.
• Increase buffer size: Settings → Capture → Buffer size (default 50,000 frames). Try 200,000.
• Tighten the BPF prefilter to drop noise at capture time.
• Capture to disk directly (File → Capture to disk…) to skip the in-memory buffer.

PCAP export produces a corrupt file

• Almost always a disk-full issue. df -h ~.
• If disk has space: try a different output path — sandbox restrictions may apply on the App Store build.

ISO / IPSW download issues

"Download failed: hostname not in allowlist"

The distro's URL doesn't match the pinned mirror. Causes:

• Distro changed mirrors — distros.json needs updating. File an issue with the new mirror URL.
• A redirect routes through a CDN we don't recognize (e.g. Cloudflare). The allowlist is strict on purpose; we'd rather refuse than trust an unknown intermediary.

"Download failed: SHA-256 mismatch"

Most often this is upstream — the mirror's checksum file changed but the ISO hasn't fully rotated yet (or vice versa). Retry in 10 minutes. If persistent, log a bug — could indicate a real supply chain issue.

Download hangs at 99%

• Network instability — abort and retry. The cache won't keep partial files.
• Disk is full — the final move from temp to cache needs space equal to the file size.

macOS guest install issues

IPSW download is very slow

Apple's CDN can be sluggish. Typical IPSW is 12–14 GB. Expect 10–30 minutes on a residential connection.

"Restore failed: invalid IPSW"

• IPSW corrupted in transit. Delete from ~/.avf/MacOS/<vm>.bundle/<version>.ipsw and retry.
• IPSW version doesn't match the chip — Apple has separate IPSWs per chip generation. SecVF should pick correctly; if it didn't, file a bug with your chip model.

Setup Assistant loops on language selection

Known macOS guest VM quirk — the framework's virtual keyboard sometimes doesn't register the first click. Force-stop, restart, click somewhere on the language screen first to focus, then proceed.

"Apple ID sign-in not available"

macOS VMs can't activate FaceTime or iMessage. Apple has restricted these to physical hardware. Skip Apple ID setup (or use a separate account) and continue.

AI sandbox issues

"Base bundle not found"

You haven't provisioned the AI sandbox base. Run the AI sandbox installer (Settings → AI Sandbox → Install base). One-time, ~30 min.

"Session clone fell back to full copy"

Your ~/.avf directory isn't on APFS. Move it to an APFS volume or accept slow cloning.

Check: diskutil info $(df -P ~/.avf | tail -1 | awk '{print $1}') | grep "File System" — must say APFS.

vsock connection times out

• The guest's vsock daemon failed to start. Check ~/.avf/AISandbox/sessions/<session>.bundle/audit.log.
• If the daemon isn't running, the base bundle is stale — re-provision it.

App crashes / hangs

SecVF beachballs

• Usually a runaway capture pipeline — the UI is starving while the table view recomputes. Stop the capture; see Capture issues.
• Switch to Activity Monitor → SecVF → Sample. The sampled stack trace usually points at the blocker.

App crashes on launch

• Check ~/Library/Logs/DiagnosticReports/ for SecVF-*.ips files.
• Most launch crashes are corrupted preferences — try defaults delete com.DaxxSec.SecVF (or the legacy com.ItzDaxxy.SecVF).
• Or corrupted state — move ~/.avf aside (mv ~/.avf ~/.avf.bak) and relaunch. If it launches, restore bundles one at a time to find the offender.

App quits when starting a VM (no crash report)

Almost always a code-signing issue. Run from Terminal: /Applications/SecVF.app/Contents/MacOS/SecVF. The terminal output will show the missing entitlement.

Performance problems

Host gets slow when VMs are running

• Sum of VM RAM allocations should be under ~75% of host RAM. macOS uses the rest for caches.
• Check sustained CPU in Activity Monitor — if SecVF is consistently >100%, a guest is spinning. Pause and investigate inside the guest.

Disk space disappearing

• VM disk images are sparse. They grow as guests write. A 64 GB allocated disk can occupy 4 GB or 60 GB on host depending on usage.
• AI sandbox sessions accumulate. du -sh ~/.avf/AISandbox/sessions/* — old session bundles can usually be deleted.
• ISO cache: du -sh ~/.avf/ISOCache — delete cached ISOs you no longer use; SecVF will re-download on demand.

Recovery procedures

Restore a VM from snapshot

1. Stop the VM (force if needed).
2. Move the broken bundle aside: mv ~/.avf/Linux/<vm>.bundle ~/.avf/Linux/<vm>-broken.bundle.
3. In SecVF: right-click your snapshot bundle → Duplicate → name it the original name.

Nuke the AI sandbox state and start over

# Stop any running AI sandbox sessions first
rm -rf ~/.avf/AISandbox/sessions
# The base bundle stays; sessions are throwaway.

Clear the ISO cache

rm -rf ~/.avf/ISOCache
# Next VM create re-downloads (slow but safe).

Reset everything

# Last resort. Loses every VM bundle and log.
osascript -e 'quit app "SecVF"'
mv ~/.avf ~/.avf.bak.$(date +%Y%m%d)
defaults delete com.DaxxSec.SecVF 2>/dev/null
defaults delete com.ItzDaxxy.SecVF 2>/dev/null
open -a SecVF

Filing a useful bug report

If you've walked the diagnostic flow and the issue is still real, file at github.com/DaxxSec/SecVF/issues. A good report has:

• Version (SecVF → About SecVF) + commit hash if you built from source.
• macOS version + chip (M1/M2/M3/Intel).
• Reproduction steps — bulleted, in order.
• Expected vs actual behaviour.
• Logs — last 100 lines of error-audit.log + the relevant slice of security-YYYY-MM-DD.log. Redact anything sensitive.
• Crash report if applicable — from ~/Library/Logs/DiagnosticReports/.

Security issues: don't file public — see Security reporting.