# Common Issues

**1. Vosk Model Not Found**

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

**Solution**:

```bash
# 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**:

```kotlin
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:

   ```kotlin
   .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**:

```kotlin
// 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:

```kotlin
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:

   ```kotlin
   @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:

   ```kotlin
   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:

   ```kotlin
   model = "google/gemini-2.5-flash-lite"  // Already fastest
   ```
4. Check conversation isn't excessively long
5. Reduce max\_tokens:

   ```kotlin
   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:

```kotlin
// 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:

```bash
adb logcat | grep Pebbl
```