You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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.
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).
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?
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 @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?
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.
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.
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.
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?
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
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.
Figma Drafting: Create visual mockups and interactive component patterns for inline warnings, modal system alerts, and full-screen critical errors.
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.
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.
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.
Activity
johnsBeharry commentedon Oct 7, 2021
There's a number of such errors documented on the following discussion
Bosch-0 commentedon Oct 15, 2021
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
GBKS commentedon Oct 22, 2021
The UI kit now includes a few screens on error handling here.
pavlenex commentedon Nov 22, 2022
Potentially we can add a new page in designing bitcoin products, (dealing with things when they go wrong) https://bitcoin.design/guide/designing-products/introduction/
GBKS commentedon Jan 5, 2024
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).
zealshah29 commentedon Apr 5, 2024
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?
GBKS commentedon Apr 15, 2024
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.
zealshah29 commentedon Apr 17, 2024
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?
GBKS commentedon Apr 17, 2024
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.
zealshah29 commentedon Apr 18, 2024
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.
GBKS commentedon Apr 18, 2024
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.
zealshah29 commentedon Apr 20, 2024
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?
elizabethmusanga commentedon Jul 7, 2026
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
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.
GBKS commentedon Jul 8, 2026
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.
elizabethmusanga commentedon Jul 9, 2026
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.