Troubleshooting
Relevant source files
The following files were used as context for generating this wiki page:
The Troubleshooting guide provides developers with the necessary information to diagnose and resolve issues within the Wizard Terminal application. This system relies on the Bubble Tea framework for TUI (Terminal User Interface) management and Lip Gloss for styling. Troubleshooting primarily involves analyzing application logs and understanding the state transitions between different input components.
The application architecture centers on a central Main model that manages a collection of Question objects, each containing an Input interface. Most issues arise during the message-passing phase within the Update function or during the rendering process in the View function.
Sources: README.md:12-14, main.go:21-36, input.go:7-16
Debug Logging
The primary tool for diagnosing runtime issues is the built-in debug logging system. The application is configured to write debug information to a local file, which is essential for capturing events that occur within the TUI environment where standard output might be obscured by the UI rendering.
Log Configuration
The application initializes a debug log file named debug.log. This file captures events from the Bubble Tea framework and any manual log entries created by the developer.
f, err := tea.LogToFile("debug.log", "debug")
if err != nil {
fmt.Println("fatal:", err)
os.Exit(1)
}
defer f.Close()
Sources: main.go:124-129
Log Analysis Flow
The following diagram illustrates how the application initializes the logging system before starting the main program loop.
The logging setup ensures that even if the program crashes during execution, the preceding events are captured in the log file.
Sources: main.go:124-133
Runtime State Issues
Errors often manifest as incorrect application states, such as the UI not updating when a user types or the application failing to progress to the next question.
State Transition Logic
The Main model tracks the current question via an index. A common point of failure is the transition logic within the Update method when the "enter" key is pressed.
| Event | Logic | Result |
|---|---|---|
ctrl+c / q | tea.Quit | Application terminates immediately. |
enter | m.index == len(m.questions)-1 | Sets m.done to true and captures the final answer. |
enter | m.Next() | Increments m.index and moves to the next question. |
WindowSizeMsg | m.width, m.height update | UI resizes to match terminal dimensions. |
Sources: main.go:73-89, main.go:109-115
Input Interface Failures
The application uses an Input interface to abstract textinput and textarea components. If a component fails to respond to input, verify that the Update method is correctly delegating messages to the underlying implementation.
The wrapper types shortAnswerField and longAnswerField must correctly proxy the Update and View calls to ensure the underlying Bubbles components receive state changes.
Sources: input.go:18-36, input.go:66-70
Visual and Rendering Issues
If the UI appears blank or misaligned, it is often due to the initial state of the terminal dimensions or Lip Gloss placement settings.
Loading Screen
If the terminal displays "loading...", it indicates that the tea.WindowSizeMsg has not yet been received or processed, meaning m.width is still 0.
Sources: main.go:101-103
Centering and Layout
The View function uses lipgloss.Place to center the UI. Troubleshooting layout issues involves checking the JoinVertical logic:
- Top Element:
current.question(String) - Bottom Element:
m.styles.InputField.Render(current.input.View())(Styled Input)
If the border is missing, verify the DefaultStyles initialization where BorderStyle(lipgloss.NormalBorder()) is defined.
Sources: main.go:15-20, main.go:105-117
Summary
Troubleshooting the Terminal Wizard involves monitoring the debug.log for framework events and verifying the state machine transitions in the Update loop. By ensuring messages are correctly passed from the Main model through the Input interface to the underlying component, developers can resolve most interactivity and rendering bugs.
Sources: main.go:71-91, input.go:7-16