Common Issues

1. Vosk Model Not Found

Symptom: App crashes when starting voice recording with error "Model not found"

Solution:

# Check if model exists in assets
ls app/src/main/assets/vosk-model-small-en-us-0.15/

# If missing, download model:
wget https://alphacephei.com/vosk/models/vosk-model-small-en-us-0.15.zip
unzip vosk-model-small-en-us-0.15.zip
mv vosk-model-small-en-us-0.15 app/src/main/assets/

# Rebuild project
./gradlew clean build

2. API Key Not Working

Symptom: AI features fail with "401 Unauthorized" error

Solution:

1. Verify API key in local.properties

2. Check key format (should start with sk-or-v1-)

3. Verify key is active on OpenRouter dashboard

4. Rebuild project to refresh BuildConfig

5. Check network connectivity

Debug:

Log.d("API_KEY", "Key: ${BuildConfig.OPENROUTER_API_KEY.take(20)}...")

3. Microphone Permission Denied

Symptom: Recording doesn't start, no error shown

Solution:

1. Check Settings → Apps → Pebbl → Permissions

2. Grant microphone permission manually

3. Restart app

4. For Android 6+, ensure runtime permission is requested

4. Network Timeout Errors

Symptom: "Network error: timeout" when generating drafts/questions

Solution:

1. Increase timeout in OkHttpClient:

   .connectTimeout(60, TimeUnit.SECONDS)
   .readTimeout(60, TimeUnit.SECONDS)

2. Check internet connectivity

3. Try switching between Wi-Fi and mobile data

4. Verify firewall isn't blocking OpenRouter

5. Room Database Migration Failure

Symptom: App crashes on launch with "Migration path not found"

Solution:

// In VoiceStreamDatabase.kt, add fallback strategy for development:
Room.databaseBuilder(context, VoiceStreamDatabase::class.java, "voice_stream_db")
    .fallbackToDestructiveMigration()  // ONLY for development!
    .build()

For production: Implement proper migrations:

val MIGRATION_4_5 = object : Migration(4, 5) {
    override fun migrate(database: SupportSQLiteDatabase) {
        database.execSQL("ALTER TABLE projects ADD COLUMN new_field TEXT")
    }
}

// Add to builder:
.addMigrations(MIGRATION_4_5)

6. Compose Preview Not Rendering

Symptom: Preview shows "Rendering Problems"

Solution:

1. Invalidate Caches: File → Invalidate Caches → Invalidate and Restart

2. Update Compose compiler version

3. Ensure preview composable has no dependencies:

   @Preview
   @Composable
   fun PreviewProjectCard() {
       ProjectCard(
           project = Project(
               id = 1,
               title = "Sample Project",
               tags = "sample, test"
           ),
           onStartSession = {},
           onViewDraft = {},
           onDelete = {}
       )
   }

7. Slow Transcription

Symptom: Vosk transcription lags behind speech

Solution:

1. Use smaller model (already using small-en-us)

2. Increase audio buffer size:

   val bufferSize = AudioRecord.getMinBufferSize(...) * 2

3. Run recognition on background thread (already implemented)

4. Close other apps to free memory

5. Test on faster device

8. Draft Generation Takes Too Long

Symptom: Draft generation exceeds 60 seconds

Solution:

1. Reduce word goal

2. Shorten conversation (fewer exchanges)

3. Switch to faster model:

   model = "google/gemini-2.5-flash-lite"  // Already fastest

4. Check conversation isn't excessively long

5. Reduce max_tokens:

   maxTokens = (wordGoal * 1.3).toInt()

Error Codes

Code	Meaning	Solution
401	Unauthorized	Check API key
429	Rate limit exceeded	Wait and retry, upgrade OpenRouter plan
500	Server error	Retry after a few seconds
503	Service unavailable	OpenRouter maintenance, try later
Network timeout	No response	Check internet, increase timeout
Model not found	Vosk initialization failed	Re-extract model from assets

Logging

Enable debug logging:

// In VoiceStreamApplication.kt
class VoiceStreamApplication : Application() {
    override fun onCreate() {
        super.onCreate()

        if (BuildConfig.DEBUG) {
            Timber.plant(Timber.DebugTree())
        }
    }
}

// Usage throughout app:
Timber.d("Recording started")
Timber.e(exception, "AI call failed")

View logs:

adb logcat | grep Pebbl