Troubleshooting and Recovery

When an error occurs during installation, Omarchy’s Troubleshooting and Recovery mechanisms help you identify the failure, seek community support, and seamlessly retry the process.

Index

1. Overview
2. Error Trapping Mechanism
3. The catch_errors Function
4. Integration in install.sh
5. User Guidance & Retry Prompt
6. Dependencies
7. Installation Failure Flowchart
8. Recovery Steps

---

Overview

Omarchy wraps its installation steps in a robust error-handling layer. If any command exits with a non-zero status, the installer:

• Prints a clear failure message with context.
• Offers a retry prompt via gum.
• Provides guidance to rerun after fixing issues.

This ensures you can quickly recover from transient errors or configuration issues without manually piecing together logs.

Error Trapping Mechanism

Omarchy leverages Bash’s set -eE and trap features to catch and handle errors:

• set -e stops execution on any failing command.
• set -E ensures ERR traps propagate within functions.
• trap catch_errors ERR invokes the catch_errors handler on errors.

These lines are set at the top of the main installer script.

#!/bin/bash
# Exit immediately if a command exits with a non-zero status
set -eE
...
source $OMARCHY_INSTALL/preflight/trap-errors.sh
...

Citation:

The catch_errors Function

Defined in install/preflight/trap-errors.sh, catch_errors performs:

• Error Notification: Prints a red “Installation failed!” banner.
• Context Output: Shows the exit code and the command that failed.
• Community Support: Displays a QR code and link to the Discord help channel.
• Retry Prompt: Uses gum confirm to ask if you want to retry immediately.

catch_errors() {
  echo -e "\n\e[31mOmarchy installation failed!\e[0m"
  echo
  echo "This command halted with exit code $?:"  
  echo "$BASH_COMMAND"
  echo
  echo "Get help from the community via QR code or at https://discord.gg/tXFUdasqhY"
  # ASCII QR/art omitted for brevity...
  if command -v gum >/dev/null && gum confirm "Retry installation?"; then
    bash ~/.local/share/omarchy/install.sh
  else
    echo "You can retry later by running: bash ~/.local/share/omarchy/install.sh"
  fi
}
trap catch_errors ERR

Citation:
Continuation:

Integration in install.sh

The error trap is sourced before any setup, guard checks, or package installations. This placement ensures all phases—from preflight checks to final reboot—are covered by catch_errors.

# Preparations
source $OMARCHY_INSTALL/preflight/show-env.sh
source $OMARCHY_INSTALL/preflight/trap-errors.sh
source $OMARCHY_INSTALL/preflight/guard.sh
...
# Finish
source $OMARCHY_INSTALL/reboot.sh

Citation:

User Guidance & Retry Prompt

Upon failure, users see:

• Exit Code & Command: Quickly pinpoint which step failed.
• Community Link: Directs to Discord for support.
• Retry Option:
  • Yes: Automatically reruns the installer.
  • No: Prints a command-line snippet for manual retry.

This approach balances automated recovery with user control.

Dependencies

• Bash 4.4+: For set -eE and trap.
• gum: Renders confirmation prompts.
  • If gum is unavailable, the prompt is skipped and only guidance is shown.

Install gum via:

{
  "commands": {
    "npm": "npm install -g gum",
    "yarn": "yarn global add gum",
    "pnpm": "pnpm add -g gum",
    "bun": "bun add gum"
  }
}

Installation Failure Flowchart

flowchart TD
  A[Start Installation] --> B[Preflight Checks]
  B --> C[Package Installation]
  C --> D[Configuration Steps]
  D --> E{Command Succeeds?}
  E -->|Yes| F[Continue Installation]
  E -->|No| G[Trigger ERR Trap]
  G --> H[Invoke catch_errors]
  H --> I{gum confirm?}
  I -->|Yes| J[Restart Installation Script]
  I -->|No| K[Show Manual Retry Guidance]
  K --> L[Exit]
  J --> A
  F --> M[Reboot]

Recovery Steps

1. Read the Error
   • Note the exit code and failing command printed by catch_errors.
2. Fix the Underlying Issue
   • Address missing dependencies, network failures, or permission errors.
3. Retry
   • Immediate: Confirm the retry prompt.
   • Later: Run bash ~/.local/share/omarchy/install.sh manually.
4. Seek Help
   • Use the provided Discord link for community support if issues persist.

---

With these built-in safeguards, Omarchy ensures you can recover gracefully from failures and complete your Arch → Hyprland installation smoothly.