# Troubleshooting — audiofiles

## Analysis Pipeline Stalls

**Symptoms:** Analysis batch stuck at a percentage, no progress events.

### Decision Tree

1. **Analysis shows error for specific sample?**
   - "Probe failed" → Unsupported or corrupted audio format. Convert to WAV/MP3 in Audacity.
   - "No audio track" → File has no playable audio stream.
   - "Decoder failed" → Codec not supported by Symphonia. Convert to WAV.
   - "No audio data" → File decoded to zero samples (silent or truncated).

2. **Batch stuck with no error?**
   - Worker thread may be stuck on a very large file
   - Cancel the batch (UI cancel button sends `WorkerCommand::Cancel` + sets `AtomicBool`)
   - Cancel takes effect after the current sample finishes processing
   - If cancel doesn't work in 30s, quit and restart app

3. **Partial results (some fields null)?**
   - `smart_skip` enabled: BPM/key/loop intentionally skipped for non-rhythmic/non-pitched samples (drums, ambience, textures)
   - If unexpected: disable `smart_skip` in analysis config and re-analyze

**WAV fallback:** WAV files that fail the Symphonia probe automatically fall back to the `hound` library.

**Analysis cap:** By default, expensive analyses (STFT, BPM, key) process only the first 30 seconds (`max_analysis_seconds`). Loudness and fingerprint always use the full signal.

## Content-Addressed Storage Corruption

**Symptoms:** "Sample not found" errors, files inaccessible.

**Storage model:** Files stored as `{sha256-hash}.{ext}` in flat directory. Hash IS the primary key.

| Symptom | Cause | Fix |
|---------|-------|-----|
| "Sample not found: {hash}" | File missing from disk or DB | Check if file exists: `ls ~/.config/audiofiles/samples/{hash}.*`. If missing, re-import from original source. |
| "Invalid hash: expected 64 lowercase hex chars" | DB corruption (hash field modified) | Find bad rows: `SELECT hash FROM samples WHERE LENGTH(hash) != 64`, delete them |
| "Cannot import zero-byte file" | Empty file | Skip — only valid audio files with content can be imported |
| Hash mismatch (file changed on disk) | Disk corruption or manual file edit | Delete corrupted file, remove DB row, re-import original |

**Verify storage integrity:**
```bash
# Count files on disk vs DB
ls ~/.config/audiofiles/samples/ | wc -l
sqlite3 ~/.config/audiofiles/audiofiles.db "SELECT COUNT(*) FROM samples"
# Numbers should match (approximately — cloud_only samples have no local file)
```

## VFS Inconsistencies

**Symptoms:** Files disappear from browser, "node not found" errors, duplicate names.

| Error | Cause | Fix |
|-------|-------|-----|
| "Node not found: {id}" | Node deleted or cross-VFS reference | Refresh view (navigate away and back) |
| "VFS not found: {id}" | VFS deleted | Create new VFS or check DB |
| "Name conflict: {name}" | Duplicate name at same directory level | Rename one of the duplicates |
| "Invalid node name" | Contains `/`, `\`, null bytes, or is `.`/`..` | Use standard filenames |
| "Move would create circular parent reference" | Moving node under its own descendant | Move to a different folder |

**Broken mirror symlinks** (Unix only): If VFS mirror has dead symlinks, re-run mirror sync (idempotent) or delete `~/audiofiles-mirror/` and restart.

**Orphaned samples** (files in store not referenced by any VFS):
```sql
SELECT hash FROM samples
WHERE hash NOT IN (SELECT DISTINCT sample_hash FROM vfs_nodes WHERE sample_hash IS NOT NULL)
AND hash NOT IN (SELECT DISTINCT sample_hash FROM collection_members WHERE sample_hash IS NOT NULL);
```

## Drag-and-Drop Platform Issues

### macOS
| Symptom | Cause | Fix |
|---------|-------|-----|
| Drag doesn't start | App not in foreground, no key window | Click window to focus, try again |
| Drag ignored on re-attempt | Previous drag still in progress (DRAG_ACTIVE flag) | Wait for first drag to complete |

### Windows
| Symptom | Cause | Fix |
|---------|-------|-----|
| Drag doesn't start | OleInitialize failed or CF_HDROP allocation failed | Restart app. If persistent, check COM initialization. |
| Drag fails with many files | Temp symlink creation fails | Check `/tmp` permissions and disk space |

### All platforms
- Drag creates temp symlinks in `/tmp/audiofiles-drag-{pid}/`
- Name collisions auto-resolved with `(1)`, `(2)` suffixes
- Large batch drags (100+ files) may be slow — try fewer files

## Database Issues

**Database location:** `~/.config/audiofiles/audiofiles.db` (platform-dependent)

**19 inline migrations** tracked via `PRAGMA user_version`. Run automatically on app startup.

| Symptom | Cause | Fix |
|---------|-------|-----|
| App won't start | Migration failed or corrupt DB | Delete DB file and restart (fresh DB). Re-import samples. |
| "database is locked" | Another process or backup tool | `lsof \| grep audiofiles.db`, close competing process |
| "FOREIGN KEY constraint failed" | Data corruption (orphaned references) | Fix: `DELETE FROM vfs_nodes WHERE sample_hash NOT IN (SELECT hash FROM samples)` |
| Slow after large import | WAL file too large | Restart app (checkpoints WAL) or: `sqlite3 audiofiles.db 'PRAGMA wal_checkpoint(TRUNCATE)'` |

**Sync changelog stuck:**
```sql
-- Check if applying_remote flag is stuck
SELECT * FROM sync_state WHERE key='applying_remote';
-- If value is '1', fix:
UPDATE sync_state SET value='0' WHERE key='applying_remote';
```

## Sync Issues

**What syncs:** VFS, samples (metadata), collections (manual and dynamic, via `filter_json`), vfs_nodes, audio_analysis, tags, collection_members, edit_history, user_config (excluding sync-internal keys and `loose_files`). Sync order respects FK relationships. Per migration M018, `sync_changelog.row_id` for sensitive tables is hashed with a per-device `row_id_salt` (never synced); the cleartext canonical key lives in the encrypted `data` field, so a lost salt makes any unpushed changelog rows un-attributable on the next push.

**Blob sync:** Sample audio files sync to cloud storage for VFS entries with `sync_files = true`. The `cloud_only` flag marks samples whose local blobs have been evicted.

| Symptom | Cause | Fix |
|---------|-------|-----|
| "Auth error: token expired" | SyncKit token expired | Re-authenticate in sync settings |
| "Sync client error: connection timeout" | Network down or server unreachable | Check internet, verify server URL |
| Sample shows "cloud only" but won't download | Upload failed or remote file deleted | Re-trigger sync. If file truly lost, re-import from original. |
| Changes don't appear on other devices | Push failed or changelog empty | Check `sync_changelog` table for unpushed entries |
| Changelog growing unbounded | Old entries never cleaned | `DELETE FROM sync_changelog WHERE pushed = 1 AND timestamp < datetime('now', '-30 days')` |

## Diagnostics Checklist

```bash
# Database integrity
sqlite3 ~/.config/audiofiles/audiofiles.db "PRAGMA integrity_check"

# Sample count: disk vs DB
ls ~/.config/audiofiles/samples/ | wc -l
sqlite3 ~/.config/audiofiles/audiofiles.db "SELECT COUNT(*) FROM samples"

# Pending sync changes
sqlite3 ~/.config/audiofiles/audiofiles.db "SELECT COUNT(*) FROM sync_changelog WHERE pushed = 0"

# WAL file size (should be <50MB normally)
ls -lh ~/.config/audiofiles/audiofiles.db-wal

# Broken mirror symlinks (Unix)
find ~/audiofiles-mirror -type l ! -exec test -e {} \; -print 2>/dev/null
```