Bug Report Template for Mobile Apps
Mobile bugs are uniquely context-dependent. A crash that reproducibly occurs on a Samsung Galaxy A32 running Android 12 may not exist at all on a Samsung Galaxy S23 running Android 14. A network-related issue that appears on a 3G connection is invisible on WiFi. Without precise device and environment context, mobile engineers can spend days trying to reproduce a bug that only appears under specific hardware and OS version combinations.
This template captures the full environmental context required to efficiently reproduce, triage, and prioritize mobile app bugs. It covers the device and OS context that determines reproducibility, the crash log collection that enables diagnosis without device access, the network conditions that reveal connectivity-dependent bugs, and the app store impact assessment that determines whether a bug requires emergency escalation — because a crash that drops your crash-free rate below 99% can directly affect your App Store search ranking.
Why mobile bug reports need more context than web bug reports
The fundamental challenge of mobile bug reporting is device fragmentation. Mobile apps run on thousands of different device models with different screen sizes, different hardware capabilities, different memory limits, and different OS versions — often with manufacturer-specific customizations (Samsung OneUI, Xiaomi MIUI) that introduce additional variation. A bug that appears only on devices with less than 3GB of RAM will be invisible to engineers testing on a development device with 12GB of RAM.
App state is the second critical dimension that web bug reports do not need to capture. Mobile apps can be in four states: foreground (active), background (suspended), killed (not running), or resumed (returning from background). Bugs that only occur when an app is resumed from background after being in memory for 30+ minutes will never reproduce in a development environment where the engineer is launching the app fresh each time.
Finally, mobile bugs have business impact beyond user experience — they directly affect app store metrics that determine discoverability. Apple's App Store deprioritizes apps with crash-free rates below 99%. A single bug affecting 2% of users (a relatively small bug in most web contexts) can drop a popular app's crash-free rate from 99.5% to 97.5%, causing a visible ranking decline. This creates an urgency classification that is unique to mobile development.
Template sections
5 sections covering the complete bug report workflow.
Device and OS context
Mobile bug reproduction depends heavily on device model, OS version, app version, storage state, and manufacturer skin. All of these must be captured for a report to be actionable. The goal is to give the engineer enough information to set up a matching test environment — or to determine that the bug is limited to a specific device configuration that can be addressed with a targeted fix.
Device context: - Device model: Samsung Galaxy A32 (SM-A325F) - OS version: Android 12 (One UI 4.1.0) - App version: 3.7.2 (build 4892) - Device RAM: 4GB (background apps may be killed more aggressively than on higher-RAM devices) - Storage: 87% full — may affect temp file operations - Manufacturer skin: Samsung One UI 4.1 (not stock Android) Simulator/emulator test: - Reproduces on physical device: YES - Reproduces on Android emulator (Pixel 5, Android 12): NO - Conclusion: Likely hardware-specific or manufacturer-specific issue
Tips
- Always include whether the bug reproduces on a simulator/emulator — this immediately tells engineers whether they can reproduce it in a development environment or need physical device access
- Include device RAM when the bug involves crashes or memory — low-RAM devices handle background processes differently and are often where out-of-memory crashes originate
- For iOS bugs: include both the iOS version AND the iPhone model name (iPhone SE, iPhone 15 Pro, etc.) — Apple devices have different screen sizes, processors, and camera hardware that affect behavior
Reproduction steps and app state
Document the exact reproduction steps with specific attention to app state transitions. Many mobile bugs only occur in specific state sequences: when the app is resumed from background, when a notification is tapped to open the app, or when the app is launched via a deep link. The reproduction steps must capture these state transitions explicitly, not just the actions within the app.
Reproduction steps: 1. Launch the app fresh (kill it first if it was previously running) 2. Log in with a standard user account (the bug does not reproduce with admin accounts) 3. Navigate to Settings > Notifications 4. Enable "Daily Digest" notifications 5. Press the Home button (send app to background) 6. Wait 30 minutes (important: the bug only reproduces after the app has been backgrounded for 20+ minutes) 7. Tap the notification when the Daily Digest notification arrives 8. OBSERVE: App crashes immediately on launch instead of navigating to the digest screen App state at time of bug: - App was in background for 30+ minutes - App may have been killed by OS and relaunched via notification (the distinction between these states is important for the crash type) Expected: App opens to the Daily Digest screen Actual: App crashes with no visible error (crash appears in Crashlytics as "Null pointer exception in NotificationDeepLinkActivity")
Tips
- Include the time-based conditions — "wait 30 minutes" sounds strange in a bug report but is critical reproduction context
- Note whether the bug reproduces via notification tap vs. direct app launch vs. deep link — each represents a different app launch pathway
- If the bug does not reproduce 100% of the time, include the reproduction rate: "Reproduces approximately 70% of the time after backgrounding for 20+ minutes"
Crash log and error collection
Attach or reference crash logs from the device or crash reporting service. Crash logs are the most direct path to diagnosis — they tell engineers exactly where in the code the crash occurred and what the state of the call stack was at the time. Without crash logs, engineers must reproduce the crash in a debugger, which may not be possible if the bug is device-specific.
Crash information: Crash reporting service: Crashlytics Crash ID: [Link to specific Crashlytics issue: https://console.firebase.google.com/u/0/project/[project]/crashlytics/app/[app]/issues/[id]] Crash summary from Crashlytics: Fatal Exception: java.lang.NullPointerException Attempt to invoke virtual method 'void com.example.app.NotificationData.getDigestId()' on a null object reference at com.example.app.NotificationDeepLinkActivity.handleIntent(NotificationDeepLinkActivity.kt:47) at com.example.app.NotificationDeepLinkActivity.onCreate(NotificationDeepLinkActivity.kt:28) Affected: 847 sessions across 312 unique users in the last 7 days Crash-free rate impact: Dropped from 99.4% to 98.6% this week (this crash is responsible for most of the 0.8pp drop)
Tips
- Always link to the specific crash issue in your crash reporting service, not just to the dashboard — engineers need the exact crash stack, not a list of all crashes
- The number of affected users and crash-free rate impact determines the priority — 312 affected users dropping your crash-free rate by 0.8pp is a high-priority issue
- If you do not have a crash reporting service: attach the device logs from Android Studio (for Android) or Console.app / Xcode Organizer crash reports (for iOS)
Network conditions and connectivity
Document the network conditions under which the bug occurs. Many mobile bugs are connectivity-dependent — they occur only on slow 4G, only when the connection drops and resumes, or only in a specific transition state (airplane mode → WiFi). This context is invisible without explicitly capturing it.
Network conditions: - Network type at time of bug: Cellular 4G LTE - Signal strength: Weak (1-2 bars) - Connected to WiFi: No - VPN active: No Network dependency test: - Strong WiFi: Does NOT reproduce - Weak WiFi (throttled to 500kbps): DOES reproduce - 4G (full signal): Does NOT reproduce - 4G (weak signal): DOES reproduce - Airplane mode → notification tap: DOES reproduce Conclusion: The bug is triggered when a notification deep link is handled while the network request to fetch the digest data times out or returns an error. The app is not handling the network failure gracefully before attempting to render the digest screen.
Tips
- Test the bug under multiple network conditions before filing the report — the pattern often reveals the root cause directly
- Weak network simulation: use iOS's built-in "Network Link Conditioner" or Android Studio's network throttling to reproduce connectivity-dependent bugs without needing an actual weak signal
- Airplane mode → notification tap is a common test case for notification-triggered bugs — it tells you whether the bug requires network access for the notification handling code
App store impact assessment and escalation criteria
Assess whether this bug affects app store metrics that require emergency escalation. Apple and Google both use crash-free rate as an app quality signal that affects search ranking. A bug that drops crash-free rate below 99% is a business-critical issue, not just a user experience issue.
App Store impact assessment: Crash-free rate impact: - Current crash-free rate: 98.6% (target: >99.5%) - This bug responsible for: ~0.8pp of the crash-free rate decline - App Store threshold: Apple flags apps below 99.0% crash-free in App Store Connect - Current status: BELOW APPLE'S THRESHOLD — App Store ranking impact is possible Review risk: - Bug-related one-star reviews in the last 7 days: 6 (searched App Store reviews for "crash" and "crash on notification") - Representative review: "App crashes every time I tap a notification. Useless." (2 stars, last Tuesday) Escalation criteria met: YES - Crash-free rate below threshold (98.6% vs 99.0% threshold) - App Store reviews mentioning the bug Recommended response: - P0: Hotfix targeting next-day release - App Store review response posted acknowledging the issue and noting the fix timeline - Customer notification: Publish a status update for affected users
Tips
- Check App Store Connect / Google Play Console for crash-free rate trends weekly — catching a decline early prevents review damage
- Respond to negative reviews that mention crashes — both stores surface recent reviews prominently, and an acknowledged crash with a fix timeline is better than silence
- A hotfix release for a crash that drops the crash-free rate below 99% is almost always the right call — the app store ranking signal recovers faster than organic reviews will recover
Copy-paste template
## Mobile Bug Report **ID:** [JIRA-XXX or GitHub #XXX] **Reported by:** [Name] | **Date:** [Date] **Severity:** [P0 — Crash affecting crash-free rate / P1 — Common path broken / P2 — Edge case / P3 — Minor] **Status:** [New / Confirmed / In Progress / Fixed] --- ### Summary [One sentence: what breaks, when it breaks, and the observable result] --- ### Device and Environment | Field | Value | |---|---| | Device model | [e.g., Samsung Galaxy A32 (SM-A325F) / iPhone SE 3rd gen] | | OS version | [e.g., Android 12 One UI 4.1 / iOS 17.3] | | App version | [e.g., 3.7.2 (build 4892)] | | Device RAM | [e.g., 4GB] | | Storage available | [e.g., 2.3GB of 64GB] | | Network type | [WiFi / 4G LTE / 3G / Offline] | | Signal strength | [Strong / Weak / Transitioning] | | Reproduces on simulator | [Yes / No — specify which simulator] | --- ### Reproduction Steps *Important: include app state context — fresh launch, from background, via notification tap, via deep link.* 1. [Step 1 — be precise about starting state] 2. [Step 2] 3. [Step 3] 4. [Any time-based or state conditions: "wait 20 minutes", "with app backgrounded"] 5. [Final action that triggers the bug] **Expected result:** [What should happen] **Actual result:** [What actually happens] **Reproduction rate:** [Always / ~X% of the time / Only under [specific conditions]] --- ### Network Conditions | Network type | Reproduces? | |---|---| | Strong WiFi | [Yes / No] | | Weak WiFi | [Yes / No] | | 4G full signal | [Yes / No] | | 4G weak signal | [Yes / No] | | Airplane mode → notification | [Yes / No] | | Offline | [Yes / No] | **Network dependency conclusion:** [Network-independent / Requires specific network state — describe] --- ### Crash Log **Crash reporting service:** [Crashlytics / Sentry / Firebase / None] **Issue link:** [Direct link to crash issue] **Crash summary:** ``` [Paste crash type, message, and top 5 stack frames] ``` **Volume:** - Affected sessions (last 7 days): [N] - Affected unique users (last 7 days): [N] - Crash-free rate impact: [-X pp — from Y% to Z%] --- ### App Store Impact | Signal | Status | Value | |---|---|---| | Crash-free rate | [Above / Below threshold] | [Current: X% — Threshold: 99.0%] | | App Store reviews mentioning bug | [N reviews found] | [Sample review] | | Escalation required | [Yes — criteria: describe / No] | | **Recommended action:** [Normal triage / Hotfix — timeline / Emergency escalation]
Frequently asked questions
Generate instead of filling in templates
Connect your tools, and Vantage generates the content using real product data. Free to start.
Free to start. No credit card required.