Design Useful Error Messages for On-Device AI

Direct answer

An on-device AI error message should name the failed stage in language the user can act on, distinguish a temporary interruption from an unsupported operation, and offer only a recovery action the app actually implements. Do not show one generic “AI failed” message for download, file verification, runtime initialization, memory pressure, backend selection, permission, task cancellation, or output parsing. Those failures have different owners and next steps. Do not surface raw native exceptions, stack traces, model prompts, transcripts, file paths, signed URLs, or tokens as user-facing copy. Build the message from a stable internal failure category rather than exception text. A lower-level component can report a stage and a safe code, such as artifact-not-present, transfer-interrupted, integrity-unavailable, access-revoked, runtime-init-failed, resource-limit, backend-unavailable, task-cancelled, or output-invalid. The UI then maps that category to a concise explanation and action. Preserve the original exception only in a protected diagnostic channel if the app’s policy allows it, and redact sensitive values before recording. A localized message should not claim a root cause the code cannot establish: “The model could not be loaded” is safer than “Your phone is incompatible” when no compatibility test supports that conclusion. Differentiate user-controlled outcomes from failures. Cancelled work is not necessarily an error; the screen can say it stopped and indicate whether the app retained valid partial state. Missing input is an empty-state condition, not an inference failure. A denied camera or file permission is a permission state that should point to the relevant system action. A low-space response should avoid telling users to delete personal content. A remote store or download service being unavailable should not be described as a model or device defect. Each message should explain what is known, what is still being checked, and what the user may do next. Keep the status machine aligned with the message taxonomy. If the manager distinguishes not-downloaded, downloading, downloaded, loading, ready, and error, UI copy should map to those states without collapsing them. “Downloaded” is not “ready”; a file can exist yet fail loading. “Cancelled” must not be presented as “corrupted.” If a verification digest is absent, do not claim integrity check success. If a runtime reports a generic error, do not guess a backend or memory cause. Ask for additional evidence or describe the uncertainty instead. Recovery language should be bounded and reversible. Retry only transient stages when the operation is idempotent or the downloader can prove the partial file belongs to the same artifact. For permission problems, explain why access is needed and let the user retry after a system grant. For resource limits, suggest reducing input scope only if the product supports that action; do not promise that closing apps will fix the model. For unsupported tasks, offer a supported path rather than “try again.” For a persistent failure, direct the user to a redacted support record that identifies app build, artifact revision, lifecycle stage, and safe failure code without including content. Review every message against its evidence. The error layer should not assert hardware incompatibility, a privacy breach, data loss, file corruption, server outage, or successful cleanup unless the component has evidence for that event. A failure to read a file may mean it was removed, access was revoked, storage disappeared, or another I/O issue occurred. The interface can report the observed failure and offer a check or retry instead of selecting one cause. Likewise, a download interruption does not prove that data was lost if a valid partial file remains.

A native load fails during an offline task

A user starts an offline translation, sees a spinner, then receives a runtime error. The app records only a load-failed event and cannot prove the phone is unsupported or that the user’s text was lost. Support needs an evidence-based next action instead of a hardware guess.

Decision

Identify the model-initialization stage, preserve retained input, offer only tested retry or support actions, and keep raw exception details out of the user-facing screen.

Expected outcome

The user receives a truthful next step without fabricated hardware diagnosis or exposed private text.

Evidence to collect

The claim becomes reviewable only when the following evidence is attached to the same artifact and test run:

• Failure taxonomy
• Recovery-action mapping
• Accessibility review

A completed byte stream is not enough. Final placement, integrity, runtime load, and recovery must also pass.

Implementation workflow

1. Map failure ownership. Associate downloader, verifier, file access, runtime, backend, task, and output parsing with a stable internal category and the exact component that can observe it.
2. Separate observation from cause. Record the observed stage and safe code. Do not infer incompatibility, corruption, privacy loss, or data deletion from a generic exception or timeout.
3. Map safe next actions. Offer retry, choose input again, grant permission, clean eligible app-owned data, choose a supported task, or contact support only if that action exists and can help the observed category.
4. Write accessible localized copy. Use a concise title, factual explanation, and one clear primary action. Announce state changes semantically and do not depend on color or unexplained native terminology.
5. Redact diagnostics. Remove prompts, transcripts, image data, raw file paths, signed URLs, request headers, and tokens before saving or sharing logs. Retain only the minimum safe build, artifact, stage, and failure category.
6. Inject representative failures. Test interruption, empty input, permission denial, missing file, missing digest, load error, resource limit, unsupported task, cancellation, and malformed output; compare message and action with the observed event.

Keep each transition observable. A failure should identify the stage, artifact, runtime, and recovery action without logging private user content.

Acceptance criteria

• Each error identifies an observed state or stage and does not invent an unsupported root cause.
• Empty state, cancellation, interruption, permission denial, unsupported operation, and actual load failure have distinct messages.
• Each recovery action is implemented, appropriate for its category, reversible when possible, and tested.
• The interface, logs, and support export do not expose user content or sensitive diagnostics.

Decision table

Failure patterns to prevent

• Showing one generic error
• Leaking raw runtime diagnostics

Also prevent silent fallback, unpinned artifacts, missing cancellation, and conclusions that combine unlike configurations. Store unsuccessful runs alongside successful ones.

Minimum reproducibility record

Release checklist

• ☐ The primary query is answered without an unsupported number.
• ☐ Every artifact and runtime is pinned.
• ☐ The representative task and failure policy are explicit.
• ☐ Lifecycle, cancellation, cleanup, and fallback are tested.
• ☐ User-content and network boundaries are documented.
• ☐ Result wording applies only to the recorded configuration.
• ☐ The page links to raw method or evidence when results are added.

Sources and related evidence

• Build an offline-first app: error handling
• Compose accessibility semantics
• Android Studio debug your app

Chinese deployment and troubleshooting content is organized in the .奇连 AI 端侧专题.

Frequently asked questions