Boot Diagnostics

Automated system health checker that detects boot issues and offers one-click fixes

Overview

Boot Diagnostics is an automated system health checker that detects common boot issues on Ubuntu systems and offers one-click fixes. It uses pure pattern matching and system queries - no LLM or AI required.

Automatic Detection

Scans journalctl and systemctl for known boot issues

Safe Fixes

User-approved fixes with sudo batching for efficiency

Severity Classification

Issues ranked by impact: Critical, Moderate, Low

Quick Start

Boot Diagnostics automatically scans on startup and shows a warning banner if issues are found.

Access via Main Menu

./start.sh

# Select "Boot Diagnostics" from the menu

Quick Scan (CLI)

./scripts/007-diagnostics/quick_scan.sh count

./scripts/007-diagnostics/quick_scan.sh summary

CRITICAL:1 MODERATE:2 LOW:0

Full TUI Interface

./scripts/007-diagnostics/boot_diagnostics.sh

Architecture

The diagnostics system follows a modular architecture with pluggable detectors:

scripts/007-diagnostics/

├── boot_diagnostics.sh     # Main TUI interface

├── quick_scan.sh           # Fast scan for startup banner

├── lib/

│   ├── issue_registry.sh   # Issue patterns & helpers

│   └── fix_executor.sh     # Batched fix execution

└── detectors/

    ├── detect_orphaned_services.sh

    ├── detect_unsupported_snaps.sh

    ├── detect_network_wait_issues.sh

    ├── detect_failed_services.sh

    └── detect_cosmetic_warnings.sh

Detectors Reference

Detector	Detects	Severity	Fixable
Orphaned Services	User services with missing executables	CRITICAL	YES
Unsupported Snaps	Snaps incompatible with Ubuntu version	CRITICAL	YES
Network Wait	Unnecessary network wait services	MODERATE	YES
Failed Services	Services that failed to start	CRITICAL	MAYBE
Cosmetic Warnings	Known harmless warnings (ALSA, etc.)	LOW	NO

Severity Levels

CRITICAL

Broken services, failed snaps, orphaned processes. Action required for system health.

MODERATE

Performance issues, unnecessary services. Recommended to fix for faster boot.

LOW

Cosmetic warnings, known Ubuntu bugs. Informational only, no action needed.

Command Reference

quick_scan.sh

Fast scanner for startup integration. Outputs issue counts without TUI.

Mode	Output	Use Case
`count`	Number of actionable issues	Startup banner condition
`summary`	`CRITICAL:N MODERATE:N LOW:N`	Startup banner text
`details`	Full issue list (pipe-delimited)	Debugging, logging
`critical`	Only critical issues	Emergency checks
`fixable`	Only fixable issues (YES/MAYBE)	Automated fix pipelines

boot_diagnostics.sh

Full TUI interface with interactive issue selection and fix application.

./scripts/007-diagnostics/boot_diagnostics.sh

# Interactive TUI with gum

# - View all detected issues

# - Select issues to fix

# - Review and approve fixes

# - Execute with batched sudo

Issue Patterns

The system detects issues by matching patterns in system logs and service status:

Pattern	Issue Type	Action
`platform.*not supported`	Unsupported Snap	`snap remove <pkg>`
`Failed at step EXEC spawning`	Orphaned Service	`systemctl --user disable <svc>`
`Timeout.*waiting for network`	Network Wait	`systemctl mask <svc>`
`GOTO.*has no matching label`	ALSA Bug (Ubuntu #2105475)	No action (cosmetic)
`unable to locate daemon control file`	Keyring PAM Timing	No action (cosmetic)

Fix Execution

Fixes are executed safely with user approval and sudo batching:

Scan system for issues
Display issues with severity
User selects issues to fix
Review generated fix commands
Batch execute with single sudo
Verify fixes applied

Fixes require sudo access. All commands are shown for review before execution.

Cosmetic Warnings (No Action Needed)

These are known issues that don't affect system operation:

Warning	Cause
ALSA GOTO label missing	Ubuntu packaging bug (#2105475)
Keyring PAM timing issue	Normal startup race condition
SCSI loop device warnings	Normal for snap packages
SATA resume warnings	Empty ports on motherboard
Kernel taint from drivers	Proprietary drivers (NVIDIA, etc.)
Bluetooth HCI limitation	Minor driver limitation
Snap desktop integration	Boot race condition (harmless)
ModemManager WiFi probe	Normal adapter behavior

Integration with start.sh

Boot Diagnostics is integrated into the main launcher:

# Automatic scan on startup

issue_count=$(./scripts/007-diagnostics/quick_scan.sh count)

if [[ $issue_count -gt 0 ]]; then

  gum style --foreground 208 "Boot issues detected: $issue_count"

fi

The main menu includes a dedicated option:

Boot Diagnostics

  ↳ Scan system for boot issues and apply fixes

Troubleshooting

Quick scan returns 0 but issues exist

Ensure journalctl access: sudo usermod -aG systemd-journal $USER then re-login.

Detector scripts not executable

Run: chmod +x scripts/007-diagnostics/detectors/*.sh

Fix fails with permission denied

System services require sudo. User services use systemctl --user without sudo.

gum not found error

Install gum: Run ./start.sh and select "Install Tools" → "gum".