android-network-bug-debugger

Android Network Bug Debugger

Purpose

Use this skill for:

• API request failures
• intermittent loading failure
• auth/token refresh bugs
• timeout or retry problems
• offline/weak-network defects
• parsing compatibility issues
• stale response overwriting newer UI state

Goals

• identify whether the bug is transport, auth, parsing, caching, concurrency, or UI-state related
• trace request lifecycle from trigger to UI update
• recommend robust fixes for weak and unstable network conditions
• define tests for retries, expiry, and out-of-order results

Inputs

Useful inputs:

• request/response logs
• Chucker or OkHttp logs
• API status codes
• parsing exceptions
• repository/use-case code
• interceptor/auth refresh code
• retry policy
• reproduction steps
• offline behavior expectations

Workflow

1. Classify failure type

Decide whether the bug is mainly:

• connectivity failure
• timeout
• TLS/certificate/config issue
• auth failure
• server error handling bug
• parsing/schema compatibility issue
• caching/staleness issue
• concurrency/race issue
• duplicate request issue
• offline UX issue

2. Trace request lifecycle

Inspect:

• trigger point
• repository/data source layer
• interceptors
• auth refresh path
• parser/serializer
• result mapping
• UI state update and error presentation

3. Look for common bugs

Check for:

• infinite refresh loops
• duplicate retries
• retrying non-idempotent requests unsafely
• swallowing HTTP error body
• treating cancellation as failure
• stale response overwriting newer request result
• missing timeout handling
• parser crash on missing/extra fields
• loading state never cleared

4. Recommend fix

Prefer:

• explicit error mapping
• token refresh serialization / single-flight
• idempotent retry policy
• stale-result protection
• tolerant parsing where contract allows
• clear offline/timeout user states
• cancellation-aware coroutine handling

Avoid:

• retrying everything blindly
• hiding all failures behind generic messages
• UI updates from obsolete requests
• blocking token refresh on main thread

5. Validation

Include:

• airplane mode
• slow network
• timeout simulation
• expired token
• duplicate tap / repeated request
• out-of-order response scenario
• schema backward compatibility checks

Output Format

1. Network Bug Summary
2. Failure Class
3. Likely Root Cause
4. Suspect Files / Request Path
5. Recommended Fix
6. Edge Cases To Retest
7. Regression Tests To Add

Good Fix Patterns

• map transport/auth/server/parsing errors separately
• serialize token refresh
• ignore stale responses for obsolete screen state
• use exponential backoff where safe
• clear loading in success/failure/cancel paths
• preserve error detail for diagnosis

Anti-Patterns

• global catch with generic "network error"
• multiple refresh attempts racing
• retry loops without cap
• parsing with overly strict assumptions when API evolves

CodeGraph Integration

CodeGraph helps trace network request lifecycles, data flow, and error handling paths.

When to run CodeGraph:

• During step 2 (trace request lifecycle) — explore the request initiation, interceptors, and response handling
• During step 3 (look for common bugs) — find auth token flows, retry logic, caching layers
• During step 4 (recommend fix) — verify the full request/response data path

codegraph explore "<repository, API service, or interceptor class>"

What to look for from CodeGraph results:

• Request initiation: ViewModel/Repository methods that call the API service
• Auth/interceptor chain: OkHttp interceptors, token refresh logic, header injection
• Response handling: JSON parsing, model mapping, error type conversion
• Caching layer: Room cache, in-memory cache, DataStore updates after network response
• Retry logic: retryWhen, retry, custom retry loops, exponential backoff
• Cancellation: coroutine cancellation handling, onCleared disposal of in-flight requests
• Timeout configuration: OkHttp client builder, per-call timeouts, connection pool settings

Scope note: CodeGraph does not reliably index AndroidManifest.xml (network permissions, network_security_config), Gradle build scripts (OkHttp/Retrofit dependency versions), or XML resource files (base URLs in string resources). For network bugs involving manifest config or build dependencies, supplement with rg/find on AndroidManifest.xml and build.gradle.

Fallback: If codegraph explore returns no meaningful results, proceed without it — CodeGraph is an enhancement, not a blocker. Fall back to rg/grep for manual request-flow search.