pub enum Error {
Io(Error),
RawModeFailure {
action: &'static str,
source: Error,
},
AltScreenFailure {
action: &'static str,
source: Error,
},
EventPoll(Error),
Render(Error),
}Expand description
Errors that can occur when running a bubbletea program.
This enum represents all possible error conditions when running a TUI application with bubbletea.
§Error Handling
Most errors from bubbletea are recoverable. The recommended pattern
is to use the ? operator for propagation:
use bubbletea::{Program, Result};
fn run_app() -> Result<()> {
let program = Program::new(MyModel::default());
program.run()?;
Ok(())
}§Recovery Strategies
| Error Variant | Recovery Strategy |
|---|---|
Io | Check terminal availability, retry, or report to user |
RawModeFailure | Check terminal compatibility |
AltScreenFailure | Disable alt screen option |
EventPoll | Terminal may be disconnected |
Render | Check output stream, retry |
§Example: Graceful Error Handling
use bubbletea::{Program, Error};
match Program::new(my_model).run() {
Ok(final_model) => {
println!("Program completed successfully");
}
Err(Error::Io(e)) if e.kind() == std::io::ErrorKind::NotConnected => {
eprintln!("Terminal disconnected, saving state...");
// Save any important state before exiting
}
Err(Error::RawModeFailure { .. }) => {
eprintln!("Terminal doesn't support raw mode. Try a different terminal.");
}
Err(e) => {
eprintln!("Program error: {}", e);
std::process::exit(1);
}
}Variants§
Io(Error)
I/O error during terminal operations.
This typically occurs when:
- The terminal is not available (e.g., running in a pipe)
- The terminal was closed unexpectedly
- System I/O resources are exhausted
- Terminal control sequences failed
§Recovery
Check if stdin/stdout are TTYs before starting your program. Consider using a fallback mode for non-interactive environments.
§Underlying Error
The underlying std::io::Error can be accessed to determine
the specific cause. Common error kinds include:
NotConnected: Terminal was disconnectedBrokenPipe: Output stream closedOther: Terminal control sequence errors
RawModeFailure
Failed to enable or disable raw mode.
Raw mode is required for TUI operation as it disables terminal line buffering and echo. This error typically indicates the terminal doesn’t support raw mode or isn’t a TTY.
§Recovery
Verify the program is running in an interactive terminal. Some terminals (especially on Windows) may have limited support.
Fields
AltScreenFailure
Failed to enter or exit alternate screen.
Alternate screen provides a separate buffer that preserves the user’s terminal content. This error may indicate the terminal doesn’t support alternate screen mode.
§Recovery
Try running without .with_alt_screen().
Fields
EventPoll(Error)
Failed to poll for terminal events.
This error occurs when the event polling system fails, typically because the terminal was disconnected or closed.
§Recovery
The terminal connection may be lost. Save state and exit.
Render(Error)
Failed to render the view to the terminal.
This error occurs when writing the view output fails, typically due to a broken pipe or disconnected terminal.
§Recovery
The output stream may be closed. Save state and exit.