Report the observation, not an assumed cause: “New entry is missing from the list until I reopen the app” is more useful than “The database is broken.” Include the starting state, expected result, actual result, build and a safe example. Keep passwords and real customer data out of the report.
Turn “the app is broken” into one observable problem
Imagine sending your developer a screenshot with the message “Save does not work.” The screenshot may show an empty list, but it does not explain what you entered, whether you tapped Save, or whether the record appears somewhere else. Describe the gap between the intended journey and the result you saw.
| Vague message | More useful title | Detail to add |
|---|---|---|
| “Save is broken.” | “New entry is absent from the list after tapping Save.” | What was entered, which screen appeared and whether the entry exists after reopening. |
| “It looks wrong.” | “The date field is covered by the keyboard on the edit screen.” | Device, orientation, text-size setting and which field had focus. |
| “It keeps crashing.” | “App closes when I open an entry with no photo.” | Steps, app build and whether the app closes or displays an error. |
Keep separate symptoms in separate reports unless they are clearly part of the same sequence. If the button is hard to see and an entry fails to save, those may need different investigation. A title should make the affected action findable later, not contain a theory about the cause.
Expected behavior should come from the agreed feature, a visible promise or a clearly stated assumption. Link to the relevant first-release acceptance example when you have one. If the intended behavior is undecided, ask a product question rather than presenting your preference as an established requirement.
Copy this mobile app bug report template
Select and copy the fields below into the private issue tracker, email or feedback route agreed with your developer. The template works for iOS, Android and Flutter projects; remove fields that genuinely do not apply and use “unknown” for details you could not establish.
Title: [Affected action + observed problem]
App and build: [Product name, version and build number; beta or store release]
Device and system: [Model, operating-system version; real device or simulator]
Starting state: [Screen, relevant test records, signed-in state if applicable]
Connection and settings: [Wi-Fi/mobile data/offline; relevant permission, language, text size or orientation]
Steps:
1. [First action from the stated starting state]
2. [Next action, including fictional values entered]
3. [Action that reveals the problem]
Expected: [Observable result that should occur]
Actual: [Observable result, exact error wording if available]
Frequency: [Observed attempts and outcomes; or happened once, not retested]
Impact: [Task blocked, inconvenience or possible data loss; distinguish confirmed from suspected]
Evidence: [Redacted screenshot/video or approved diagnostic attachment]
Comparison or workaround: [What you actually tested; or not tested]
Unknowns: [What you have not checked]
Observed time: [Date, time and time zone if relevant]
The app version and build number are not the same as the phone’s operating-system version. Check the app’s About screen or the beta-build information if available. If only the app version is visible, provide it and mark the build unknown. Do not infer an installed version from the newest version listed in a store.
Include settings only when they may affect the symptom. “Large text enabled; portrait orientation” helps investigate a clipped field. A phone serial number, advertising identifier or exact home address does not belong in a routine layout report.
See a filled example without pretending to know the cause
The report below is a fictional example for an invented reading-log app. Its builds, device label, records and results are made up to demonstrate the format. It is not a bug in a Moocsoft product or a customer incident.
Title: New reading entry is missing from the list until the app reopens.
App and build: Fictional Reading Log, test version 0.4.0, build 12.
Device and system: Example Phone A, Android 14, real test device.
Starting state: Entries screen is empty; no account is used.
Connection and settings: Wi-Fi connected; portrait; default text size.
Steps:
1. Open Entries and tap Add.
2. Enter the fictional title “Sample Book A” and date 12 October 2026.
3. Tap Save and look at the returned Entries screen.
Expected: The agreed save journey returns to Entries and shows the new title and date.
Actual: The app returns to Entries, but no row is visible in two of three observed attempts. No error appears. After closing and reopening, the saved row is visible.
Frequency: Two of three attempts, using a fresh empty test list before each attempt.
Impact: Cannot confirm the save from the returned list. Data loss is not demonstrated; the record appears after reopening.
Evidence: Redacted screen recording of one affected attempt using fictional data.
Comparison: Reopening shows the record. Another device and offline use have not been tested.
Unknowns: Cause, behavior on iOS and whether older builds are affected.
This report does not conclude that the database failed, the network failed or Flutter caused the issue. It records what was visible and what a later check revealed. Those distinctions give the maintainer several places to investigate without turning a guess into a requirement.
“Two of three attempts” describes this small set of observations, not a measured failure rate for all users. Include the successful attempt too. An intermittent result is still reportable when you explain which conditions were held constant and which remain unknown.
Capture evidence safely, then change one condition at a time
A short recording can show the starting screen, action and result more clearly than a screenshot of the final state. Use fictional entries in an approved test build where possible. Before attaching media, inspect notifications, account details, names, photos and background screens. Crop or obscure information that is not needed to understand the symptom.
Use the project’s private feedback route for private evidence. Do not paste credentials, authentication tokens, signing keys or production records into a public issue. Diagnostic logs can contain sensitive details too; agree which excerpt is needed and how it should be shared. Redaction should remove unrelated private information without replacing the error wording that matters.
For an iOS beta, Apple’s TestFlight guidance describes feedback through TestFlight and supported screenshot-feedback flows. Use the route available for your test build and include a written explanation; a screenshot alone still lacks the steps.
If it is safe to retest, repeat the original steps first. Then try one relevant comparison, such as the same steps offline or with a different text-size setting. Record the changed condition and outcome. If you change the build, device, connection and records together, you cannot tell which difference mattered.
Do not uninstall an app, clear its data, submit repeated payments or delete production records just to gather evidence. Those actions can create a second problem. When data loss, billing or a security issue is suspected, stop unnecessary retries and contact the responsible maintainer through the agreed private route. State what happened without publishing the affected data.
Agree on the next check and retest the actual fix
The receiving developer can record whether they reproduced the symptom, need more detail or identified an unresolved product decision. “Not reproduced on my device” is a result under that setup, not proof that your observation did not happen. Compare the build, starting records and conditions before closing the report.
For a framework-level issue, Flutter’s useful bug report guide asks developers for a small reproducible app and relevant diagnostics or recent logs. That is a developer investigation step. A nontechnical tester should not need to create a Flutter project or run development commands to report what they saw.
When a test build is ready, rerun the original steps and record the new version and build. Check both the visible result and the saved record when persistence is involved. In the fictional example, that means confirming the row appears after Save and remains present after reopening. Record any untested device or condition rather than declaring every platform fixed.
Keep the final status precise: reported, reproduced, changed in a test build, retested or released. A fixed beta is not automatically available to everyone in the store. Carry unresolved issues into the mobile app handover record instead of losing them in chat.
Planning a new app or improving an existing Flutter project? Explore Moocsoft’s Flutter development service and bring the main user journey, current materials and a report like this. A concrete example gives the project discussion something observable to work from.
Common questions
Do I need coding knowledge to report a mobile app bug?
No. Give the starting state, steps, expected and actual behavior, app build and device details you know. You can leave the technical cause unknown. A developer can request relevant diagnostics separately.
What if I cannot reproduce the bug every time?
Report the observation and the attempts you actually made. State which attempts showed the problem, the conditions used and what remains untested. Do not turn a few attempts into a claim about the failure rate for all users.
Is a screenshot enough for a bug report?
A screenshot can support the report, but it usually does not identify the starting state, steps or build. Include a written description and, when safe and useful, a redacted recording of the action.
Should I uninstall the app before reporting a problem?
Do not uninstall or clear data merely to investigate if that might remove records. Preserve the relevant observation and use a safe test build or instructions from the responsible maintainer. Avoid destructive or paid production actions during reproduction.
Is a requested new feature the same as a bug?
A bug report describes behavior that differs from an agreed or documented expectation. If the intended behavior is undecided or you want a new capability, describe the user need as a product question or feature request instead.
References and further reading
Published by Moocsoft, an independent Flutter development studio. Examples and worksheets are illustrative. Project scope, platform requirements and release responsibilities need to be agreed for each project.