# Android TV Catalog Debugging

## Error-Message-Blocking-Content Trap

When a `when` block checks `errorMessage != null` before the main content `else` branch, it blocks ALL
content — including priority rows (Continue Watching, hero) that don't need the failing API.

**BROKEN:**
```kotlin
when {
    uiState.isLoading -> LoadingSpinner()
    uiState.errorMessage != null -> ErrorMessage(message)  // blocks everything
    else -> LazyColumn { ... }
}
```

**FIXED:** Use a non-blocking banner inside the content area:
```kotlin
when {
    uiState.isLoading -> LoadingSpinner()
    else -> LazyColumn {
        if (uiState.catalogsUnavailable) {
            item { WarningBanner("Catalogs unavailable — check API key") }
        }
        // Priority rows + catalog rows render below
    }
}
```

**Rule:** `errorMessage` should only be used for CRITICAL errors (network down, auth required).
For missing API keys, degraded catalogs, or partial failures, use `warningMessage` or
`catalogsUnavailable` with an inline banner.

## TMDB API Key Debugging

See `nexstream-android-tv-build` references for full TMDB auth debugging workflow.
Summary: v3 keys (32 hex) → `api_key` query param; v4 tokens (JWT `eyJ...`) → `Authorization: Bearer`.
Test with Python `urllib` before assuming app code is wrong.