Skip to content

Create a page for designing error states #505

Open

Description

@GBKS

This is based on this Tweet I posted about how to provide useful information to users when things go wrong. There was a very positive response to the post. Errors are typically not things builders enjoy detailing out, but they are hugely important to build trust and confidence in a product. It's an area where we could provide a good foundation that might save others time and effort. There's also a Slack thread about this.

Might be ideal to have one page about how to generally approach errors (maybe in Designing Bitcoin products), and individual pages and sections could address unique errors.

Some notes on potential errors page content:

  • General approach
    • Differentiate between user error and technical error
    • Do everything you can to prevent errors in the first place by guiding users well and using under-the-hood tech approaches (X didn't work, try Y before bugging users)
    • Psychology of error messages (clearly state what happened in simple language, calm user concerns, suggest solutions if possible, offer simple follow-up actions)
  • Try to find error severity categories. Examples:
    • Minor form validation (forgot to fill out a field, etc)
    • Data validation where user might need help (BTC address invalid)
    • Service problem (no route found to a node)
    • Application problem that can't be avoided (app crashes)
  • Try to find solution proposal categories. Examples:
    • Problem is unfixable
    • Not sure what happened, ask for support (share this error log in our Telegram channel for help)
    • Problem can maybe be fixed if the user tries a few things (try one of these)
    • Problem can be fixed by the user with a specific action (do this)
    • App can probably fix the problem by doing something unusual, but needs user permission (is it OK to do this?)
    • Retry later
  • Design mock-ups with detailed explanations for different error scenarios

Goal with these points is to structure an approach to designing for these user experiences. I think we can end up with fairly straightforward system and guidance.

Helpful errors 211006

Activity

  1. added
    CopyTask is about improving text.
    on Oct 6, 2021
  2. johnsBeharry commented on Oct 7, 2021

    @johnsBeharry
    Contributor

    There's a number of such errors documented on the following discussion

  3. Bosch-0 commented on Oct 15, 2021

    @Bosch-0
    Collaborator

    Here are some Lightning error codes we should design human readable error messages for on this page: https://wiki.ion.radar.tech/tutorials/troubleshooting/error-codes

  4. GBKS commented on Oct 22, 2021

    @GBKS
    ContributorAuthor

    The UI kit now includes a few screens on error handling here.

  5. added
    DesignTask is about designing something.
    and removed on Apr 11, 2022
  6. pavlenex commented on Nov 22, 2022

    @pavlenex
    Contributor
  7. GBKS commented on Jan 5, 2024

    @GBKS
    ContributorAuthor

    I still think this is a good issue. Basically extract what we have in the sending page and add some more meat around it. I'd like to add this to the roadmap for Q1, for myself to work on (unless there are other takers).

  8. self-assigned this
    on Jan 5, 2024
  9. zealshah29 commented on Apr 5, 2024

    @zealshah29

    Hi, so I was going through the following issue and wanted to know if it's about creating all the possible error states for just the sending page or all the possible pages of bitcoin wallet?

  10. GBKS commented on Apr 15, 2024

    @GBKS
    ContributorAuthor

    Hi @zealshah29, the description of the issue has a pretty good outline. The goal is not to create all possible error states, but to provide a framework for presenting errors and allowing users to deal with them, and then mock-ing up a solid set of examples. So many different things can go wrong across different application that it would be really hard to capture all possible error states.

  11. zealshah29 commented on Apr 17, 2024

    @zealshah29

    Hi @zealshah29, the description of the issue has a pretty good outline. The goal is not to create all possible error states, but to provide a framework for presenting errors and allowing users to deal with them, and then mock-ing up a solid set of examples. So many different things can go wrong across different application that it would be really hard to capture all possible error states.

    Hi @GBKS ,
    Thank you for your feedback and clarification on the goal for the error handling framework. I would love to help out with both the content and designing UI mock-ups for the error page. Could you let me know what has been done so far?

  12. GBKS commented on Apr 17, 2024

    @GBKS
    ContributorAuthor

    No one is working on this at the moment. You are welcome to work on this, but just as a heads up, this is a pretty complex issue that will be quite involved.

  13. zealshah29 commented on Apr 18, 2024

    @zealshah29

    Okay, thank you. Could you kindly provide information about the timeframe for completing this task? Knowing the deadline will assist me in determining my capacity to contribute effectively. If there's no specific timeframe, I'm prepared to engage and offer my assistance. I can establish milestones and provide regular updates as needed.

  14. GBKS commented on Apr 18, 2024

    @GBKS
    ContributorAuthor

    There is no timeframe for this, it is a completely open task that you are welcome to tackle as it works best for you. It is always helpful to do these things step by step and in collaboration with the others who work on the guide. We have a dedicated channel for the project in our Discord, and host calls about the project every other week, which you can find in the calendar. I'm looking forward to see what you'll come up with.

  15. zealshah29 commented on Apr 20, 2024

    @zealshah29

    Thank you so much, I am looking forward to it. Just wanted a quick clarification. Since this project is a part of the Bitcoin Design Guide, will it be discussed in the Bitcoin Design Guide Jam sessions or will there be separate project calls for the same?

  16. elizabethmusanga commented on Jul 7, 2026

    @elizabethmusanga

    Hi @GBKS

    Following up on the conversation here, I see this issue is still open and I would love to take it on this July. Based on the links shared in the discussion thread, I see a great opportunity to pull from the current patterns and consolidate them into a dedicated, foundational page under the "Designing Products" directory (e.g., handling things when they go wrong).

    My plan is to break this down into digestible milestones

    1. Audit & Synthesis: Map out and document all existing error states currently referenced across the Guide and the Bitcoin UI Kit to create a unified archetype list.
    2. Figma Drafting: Create visual mockups and interactive component patterns for inline warnings, modal system alerts, and full-screen critical errors.
    3. Copy & Translation Guidelines: Draft a lightweight framework on translating technical protocol friction (e.g., node offline, channel capacity limits, routing failures) into transparent, stress-free microcopy.

    If this sounds good and the task is still free, please go ahead and assign it to me so I can get started on the initial audit stage.

  17. GBKS commented on Jul 8, 2026

    @GBKS
    ContributorAuthor

    Hi Elisabeth. Thanks for your interest in working on this. You are more than welcome to chip in, I'll assign it to you.

    Maybe one additional research task could be to see how errors are handled in other wallets. They often have forums or chats (Telegram, etc) where people ask for support. If certain errors are mentioned often, maybe that's an indication that apps don't handle them well. Just an idea, feel free to ignore.

  18. elizabethmusanga commented on Jul 9, 2026

    @elizabethmusanga

    I think looking into other wallets' support channels is a fantastic, holistic approach to finding real user pain points. I’d love to take on that research part as well and will weave it into my initial audit. Thanks.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Labels

CopyTask is about improving text.DesignTask is about designing something.

Type

No type

Projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions