Troubleshooting Guide Template¶

# Problem: [Brief Description]

**Symptoms**:
- What the user sees/experiences
- Error messages
- Unexpected behavior

**Common Causes**:
1. Cause 1 (most common)
2. Cause 2
3. Cause 3

## Diagnosis

### Step 1: Check [X]
How to check:
\```bash
command to run
\```

Expected output:
\```
expected result
\```

If different: [What it means]

### Step 2: Verify [Y]
[Diagnostic steps]

### Step 3: Test [Z]
[More steps]

## Solutions

### Solution 1: [Most Common Fix]
**When to use**: [Conditions]

**Steps**:
1. Step one
2. Step two
3. Step three

**Verification**:
\```bash
command to verify fix
\```

### Solution 2: [Alternative Fix]
[Details]

### Solution 3: [Advanced Fix]
[For complex cases]

## Prevention

**How to avoid this in future**:
- Prevention tip 1
- Prevention tip 2

## Related Issues

- #123 - Related issue 1
- #456 - Related issue 2

## See Also

- [Related troubleshooting guide](link)
- [Architecture doc](link)

Example: Audio Glitches¶

Problem: Audio Crackling/Glitches¶

Symptoms: - Audible clicks, pops, or dropout - Irregular or periodic - May worsen under CPU load

Common Causes: 1. Buffer underrun (CPU can't keep up) 2. Real-time violations (allocations, locks) 3. Denormal numbers 4. Thread priority issues

Diagnosis¶

Step 1: Check CPU Usage¶

# Profile audio callback
perf record -g ./audio_app
perf report

If > 70% of buffer time: Buffer underrun likely

Step 2: Run Real-Time Validator¶

RTSafetyValidator validator;
validator.checkAudioThread();
// Look for allocations, locks

Step 3: Check for Denormals¶

// Add to audio callback temporarily
if (std::fpclassify(sample) == FP_SUBNORMAL) {
  LOG("Denormal detected!");
}

Solutions¶

Solution 1: Increase Buffer Size¶

When to use: CPU usage high, glitches under load

Steps: 1. In DAW settings, increase buffer size (256 → 512 or 512 → 1024) 2. Test if glitches disappear 3. If solved: Optimize code or accept higher latency

Solution 2: Fix Real-Time Violations¶

When to use: Validator finds allocations/locks

Steps: 1. Remove allocations from audio thread 2. Pre-allocate buffers 3. Use lock-free structures 4. Move I/O to separate thread

Solution 3: Flush Denormals¶

When to use: Denormals detected

Steps:

// At start of process()
_MM_SET_FLUSH_ZERO_MODE(_MM_FLUSH_ZERO_ON);
_MM_SET_DENORMALS_ZERO_MODE(_MM_DENORMALS_ZERO_ON);

Prevention¶

Profile regularly
Use RTSafetyValidator in tests
Benchmark on low-end hardware
Test with small buffer sizes (64, 128)