← Build log

When Your App Randomly Eats User Data: A Defense-in-Depth Guide for Solo Builders

Originally published: [Date]

You know that sinking feeling when a user reports your app “sometimes just loses things”? Not always, not predictably, just… sometimes. It’s like debugging with a blindfold while someone occasionally moves the furniture.

I just spent the better part of a day hunting down an intermittent text loss bug in VoiceCatcher where the app would capture the first sentence perfectly, then drop three or four sentences, and mysteriously resume transcribing. Users would say 10 sentences and get back 3. Not exactly the “reliable voice capture” experience we were going for.

The real kicker? The bug was happening in a completely different part of the system than I initially thought. What I learned about defensive coding and systematic debugging might save you from your own 2 AM “why does this work on Tuesday but not Wednesday” sessions.

TLDR

What You’ll Gain:

  • A systematic approach to hunting intermittent bugs that could save you 10+ hours per mystery issue
  • Defensive coding patterns that catch problems before they reach users
  • Copy-paste AI prompts for code analysis that actually work
  • A debugging framework for complex systems with multiple failure points
  • Bottom Line Value: Stop losing users to “it works fine on my machine” bugs and build systems that fail gracefully instead of silently.

The Problem: When “Working” Isn’t Actually Working

Here’s what made this bug particularly evil: VoiceCatcher appeared to be working perfectly. The recording started, the transcription completed, text appeared in the clipboard. Success, right?

Except users were reporting that half their sentences were missing. The audio was captured, Whisper was processing it, post-processing was running, text was being copied. Every component reported success. Yet somehow, sentences were vanishing into the digital ether.

This is the kind of bug that makes you question your career choices. Everything looks fine in the logs, tests are passing, but real users are losing their data. Sound familiar?

The Investigation: Following the Wrong Breadcrumbs

My first instinct was to blame the post-processing pipeline. Text manipulation code? That’s where text gets lost, right? I spent hours implementing defensive measures:

// Paranoid word count validation everywhere
function cleanupParagraphBreaks(text, isShort = false) {
  const originalWordCount = countWords(text);
  console.log(`[SAFETY] Starting with ${originalWordCount} words`);

  // ... processing logic ...

  const finalWordCount = countWords(result);
  if (finalWordCount < originalWordCount * 0.9) {
    console.error(`[EMERGENCY] Word loss detected! ${originalWordCount} → ${finalWordCount}`);
    return text; // Return original on any loss
  }

  return result;
}

I built a comprehensive safety net: word count validation, emergency fallbacks, extensive logging. The post-processing tests came back perfect - 51 words in, 51 words out.

But users were still losing text.

The Breakthrough: Looking Upstream

Here’s where systematic debugging saved the day. Instead of assuming I knew where the problem was, I traced the data flow from start to finish:

  1. Audio Recording ✅ (File size looked correct)
  2. Audio Preprocessing ❓ (Wait, what’s this doing?)
  3. Whisper Transcription ✅ (Getting some output)
  4. Post-Processing ✅ (Now bulletproof with safety checks)

The smoking gun was in the logs: Whisper was processing a file called recording_cleaned.wav, not the original recording.wav. Something was preprocessing the audio before transcription.

Bingo. The text wasn’t being lost in post-processing. It was being lost because the audio preprocessing was corrupting the audio file, giving Whisper incomplete audio to transcribe.

The Real Problem: Complex Audio Pipeline Gone Wrong

Buried in the codebase was this audio preprocessing function:

async function preprocessAudioForWhisper(inputPath) {
  // Complex SoX operations with multiple steps
  const tempPath = path.join(tempDir, 'temp_processed.wav');
  const finalPath = path.join(tempDir, 'recording_cleaned.wav');

  // Two-step processing with trim operations
  await runSoxCommand([
    inputPath,
    tempPath,
    'trim',
    '0.1', // Remove leading silence
    'norm',
    '-0.3', // Normalize audio
    'lowpass',
    '8000', // Filter frequencies
    'compand',
    '0.3,1',
    '6:-70,-60,-20',
    '-5',
    '-90',
    '0.2',
  ]);

  await runSoxCommand([
    tempPath,
    finalPath,
    'trim',
    '0',
    '-0.1', // Remove trailing silence
    'rate',
    '16000', // Convert sample rate
  ]);

  return finalPath;
}

The trim operations designed to remove “silence” were sometimes removing actual speech. The complex SoX pipeline had multiple failure modes, and when it failed, it failed silently - producing a shorter audio file that Whisper would dutifully transcribe, resulting in missing sentences.

The Fix: Defense in Depth

Instead of trying to perfect the audio preprocessing (a rabbit hole that could take weeks), I implemented a defensive architecture:

1. Circuit Breaker Pattern

// Disable risky preprocessing temporarily
async function transcribeAudio(audioPath) {
  // Skip preprocessing entirely for now
  const transcriptPath = audioPath; // Use original file

  // Add validation to catch any remaining issues
  const audioStats = await getAudioStats(audioPath);
  if (audioStats.duration < 0.5) {
    throw new Error('Audio too short - possible corruption');
  }

  return await runWhisperTranscription(transcriptPath);
}

2. Comprehensive Logging

console.log(`🔧 DEBUGGING: Audio file size: ${audioStats.size} bytes`);
console.log(`🔧 DEBUGGING: Duration: ${audioStats.duration} seconds`);
console.log(`🔧 DEBUGGING: Whisper command: ${whisperCommand}`);
console.log(`🔧 DEBUGGING: Raw output length: ${transcript.length} characters`);

3. Fallback Mechanisms

// Always provide a way back to working state
if (preprocessingEnabled && preprocessingFails) {
  console.warn('Preprocessing failed, using original audio');
  return await transcribeWithOriginalAudio(originalPath);
}

Bonus Bug: The Settings Persistence Nightmare

While fixing the audio bug, I discovered another intermittent issue: settings would randomly reset when users navigated between UI sections. The slider would show 2.5 seconds, but after clicking away and back, it would show 1.5 seconds.

This turned out to be a classic state management anti-pattern: dual sources of truth.

The app had three separate settings systems:

  1. React hook state (useSettings)
  2. Local component state (useState)
  3. Electron store persistence

When users adjusted sliders, the changes would save to the Electron store, but the React components weren’t refreshing their state from storage when re-rendering.

The fix was simple but critical:

// Add refresh function to useSettings hook
const refreshSettings = useCallback(async (): Promise<void> => {
  const refreshedSettings: VoicecatcherSettings = await window.electronAPI.getSettings();
  setSettings(refreshedSettings);
  setSilenceDuration(refreshedSettings.silenceTimeoutMs / 1000);
  // ... update all state from fresh storage values
}, []);

// Automatically refresh when navigating between sections
const openEssentialSettings = () => {
  setEssentialExpanded(true);
  setAdvancedExpanded(false);
  refreshSettings(); // Critical: re-fetch latest values
};

High-Value AI Prompts for Debugging

Here are the exact prompts I used with Claude that actually helped solve these issues:

1. Systems Analysis Prompt

Analyze this codebase for potential intermittent failure modes. Look specifically for:
- Audio/file processing pipelines with multiple steps
- State management with multiple sources of truth
- Race conditions in async operations
- Silent failure modes where errors don't bubble up
- Complex operations that could partially succeed

Focus on the data flow from [entry point] to [exit point] and identify the most likely points of failure.

2. Defensive Coding Review Prompt

Review this function for defensive coding patterns. Add:
- Input validation and sanitization
- Comprehensive error handling with specific error types
- Fallback mechanisms for each failure mode
- Logging that helps with debugging in production
- Circuit breaker patterns for risky operations

Assume this will run in production with real user data and needs to fail gracefully.

3. Root Cause Analysis Prompt

Given these symptoms: [describe user-reported behavior]
And these logs: [paste relevant logs]
And this system architecture: [brief description]

Walk through the most likely failure scenarios step by step. For each scenario, explain:
- What would cause this behavior
- How to test if this is the root cause
- What the logs would show if this were happening
- How to fix it permanently

Prioritize scenarios by likelihood and impact.

The Solo Builder’s Debugging Checklist

When facing intermittent bugs in complex systems:

✅ Before You Start

  • Reproduce the issue at least 3 times
  • Document exactly what users are doing when it happens
  • Check if there are patterns (time of day, specific actions, etc.)
  • Gather comprehensive logs from affected sessions

✅ During Investigation

  • Map the complete data flow from input to output
  • Identify every transformation step where data could be lost
  • Check for multiple sources of truth in state management
  • Look for async operations that could race or timeout
  • Test each component in isolation

✅ When Implementing Fixes

  • Add defensive validation at every boundary
  • Implement circuit breakers for risky operations
  • Create fallback paths for when things go wrong
  • Add comprehensive logging for post-mortem analysis
  • Write tests that specifically target the failure modes

✅ After Deployment

  • Monitor logs for the specific patterns you fixed
  • Set up alerts for the defensive measures triggering
  • Document the failure mode for future reference
  • Share lessons learned with your team (or blog about it!)

What This Means for Us

As solo builders, we don’t have the luxury of dedicated QA teams or extensive testing infrastructure. But we also can’t afford to lose users to mysterious bugs. The key is building defensive systems that assume things will go wrong.

The audio preprocessing bug taught me that complexity is the enemy of reliability. When in doubt, choose the simpler path that you can understand and debug. The settings persistence bug reminded me that state management is always more complex than it appears on the surface.

Both bugs were caught because I implemented comprehensive logging and defensive validation. When things inevitably go wrong (and they will), you want enough information to understand what happened.

The best part? These defensive patterns make your system more robust without adding significant complexity. A few validation checks and fallback paths can save you hours of debugging and prevent users from losing their data.

For solo builders specifically, this approach scales better than trying to prevent every possible failure. Build systems that fail fast and fail obviously, rather than systems that fail silently and mysteriously.

Your users will thank you for it.

P.S. - While writing this post, VoiceCatcher’s text enhancement spotted that I had inconsistent formatting in my code examples and fixed it automatically. The defensive coding is already paying dividends.