> For the complete documentation index, see [llms.txt](https://orbitron.gitbook.io/orbitron-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://orbitron.gitbook.io/orbitron-docs/user-guide/installation/troubleshooting.md).

# Troubleshooting

This guide covers common issues that may occur during Orbitron installation and auto-update, along with their solutions.

## 1️⃣ Newly Installed but Old Version Keeps Running

### Symptoms

```bash
# After running the installation script...
$ orbitron --version
v0.1.11  # Old version is displayed

$ which orbitron
/Users/username/.orbitron/bin/orbitron  # Or /usr/local/bin/orbitron
```

### Causes

* Previous installation location has higher priority in PATH
* Terminal is caching the old path
* Installation succeeded but PATH settings haven't been applied

### Solutions

**Step 1: Restart Terminal**

The simplest approach:

**Unix/Linux/macOS:**

```bash
# Restart shell
exec $SHELL

# Or just reset command cache
hash -r

# Verify version
orbitron --version
```

**Windows:**

```powershell
# Close PowerShell completely
exit

# Open new PowerShell window
orbitron --version
```

**Step 2: Remove Old Installation (Recommended)**

The most reliable method is to remove the old installation:

**Unix/Linux/macOS:**

```bash
# Remove old installation
rm -rf ~/.orbitron

# Restart terminal
exec $SHELL

# Verify
orbitron --version
which orbitron  # Should be /Users/username/.local/bin/orbitron
```

**Windows:**

```powershell
# Remove old installation
Remove-Item -Recurse -Force "$env:USERPROFILE\.orbitron"

# Restart PowerShell and verify
orbitron --version
```

**Step 3: Reinstall (If All Else Fails)**

```bash
# Unix/Linux/macOS
curl -fsSL https://orbitron.megaone.com/api/install.sh | bash

# Windows
irm https://orbitron.megaone.com/api/install.ps1 | iex
```

If a migration prompt appears during installation, select **YES**.

***

## 2️⃣ Auto-Update Enabled but Not Updating

### Symptoms

```bash
# Auto-update is enabled...
$ orbitron config get autoUpdate
true  # Enabled

# But new version has been released and no update
$ orbitron --version
v0.1.12  # Old version (latest is v0.1.13)
```

### Understanding Auto-Update Behavior

**Important:** Auto-update works as follows:

1. **Every 6 hours** checks for new versions in the background
2. Automatically downloads and installs new versions when available
3. **On next execution** automatically switches to the new version

This means updates don't happen immediately after enabling the setting; you must wait for the next 6-hour check cycle.

### Solution

If you need an immediate update, re-run the installation script:

**Unix/Linux/macOS:**

```bash
curl -fsSL https://orbitron.megaone.com/api/install.sh | bash
```

**Windows:**

```powershell
irm https://orbitron.megaone.com/api/install.ps1 | iex
```

***

## 3️⃣ Program Terminates Due to Critical Update

### Symptoms

When running Orbitron, it automatically terminates with a message like this:

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
              ⚠️  Critical Security Update Required
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Current version: v0.1.9
Required version: v0.1.13

This update is required for security and stability.
Your work in progress has been automatically saved.

How to update:
  curl -fsSL https://orbitron.megaone.com/api/install.sh | bash

Installation guide:
  https://alphacode-ai.gitbook.io/orbitron/user-guide/installation

Exiting to prevent running a vulnerable version.
```

### Reason

A required update containing security patches or critical bug fixes has been released. In this case, the program terminates regardless of your auto-update settings.

### Solution

**Unix/Linux/macOS**

Run the command shown in the message:

```bash
curl -fsSL https://orbitron.megaone.com/api/install.sh | bash
```

After installation:

```bash
orbitron --version  # Verify new version
orbitron  # Run normally
```

**Windows**

```powershell
irm https://orbitron.megaone.com/api/install.ps1 | iex
```

After installation:

```powershell
orbitron --version  # Verify new version
orbitron  # Run normally
```

***

## 4️⃣ Warning Messages During Installation Script

### Warning 1: Migration Prompt

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Old Installation Detected
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Old version: v0.1.12 (in ~/.orbitron/bin/)
New version: v0.1.13 (will be installed to ~/.local/bin/)

Would you like to migrate the old installation?
  YES: Backup old version, install new version, update PATH
  NO:  Keep both versions (you can remove old version later)

Migrate old installation? (Y/n):
```

**Recommended Choice:** `Y` or `Enter` (YES)

**If you select YES:**

* Old version is backed up (`~/.local/share/orbitron/versions/0.1.12/`)
* Binary removed from old installation location
* New version installed
* PATH automatically updated

**If you select NO:**

* Both versions are kept
* You can remove the old version later with `rm -rf ~/.orbitron`

### Warning 2: Auto-Update Configuration

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Auto-Update Configuration
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Would you like to enable automatic updates?
You can change this setting later with: orbitron config set autoUpdate <true|false>

Enable auto-update? (Y/n):
```

**Recommended Choice:** `Y` or `Enter` (YES)

**Meaning:**

* **YES:** Automatically check for and update to new versions every 6 hours
* **NO:** Manual update script execution required

**Can be changed later:**

```bash
# Enable
orbitron config set autoUpdate true

# Disable
orbitron config set autoUpdate false
```

***

## 5️⃣ Command Not Found (command not found)

### Symptoms

```bash
$ orbitron
command not found: orbitron
```

### Solution

**Step 1: Restart Terminal**

```bash
# If using Zsh
source ~/.zshrc

# If using Bash
source ~/.bashrc
```

**Step 2: Reinstall**

If that doesn't work, re-run the automated installation script:

```bash
# Unix/Linux/macOS
curl -fsSL https://orbitron.megaone.com/api/install.sh | bash

# Windows
irm https://orbitron.megaone.com/api/install.ps1 | iex
```

***

## 6️⃣ Orbitron Cannot Recognize or Execute AWS Commands on Windows

### Symptoms

* The AI tries to run an `aws` command but it fails with no output, or the command is not recognized
* The command output is empty, leading the AI to draw incorrect conclusions

### Cause

Orbitron's command execution defaults to a Unix-style shell (`/bin/bash`). Windows has no bash by default, so the commands never run. Installing **Git Bash** and pointing the shell path to it resolves the issue.

### Solution

**Step 1: Install Git for Windows**

Download and run the installer from the [Git for Windows download page](https://gitforwindows.org/). You can leave all installer options at their defaults.

To check whether it's already installed, run in PowerShell:

```powershell
Test-Path "C:\Program Files\Git\bin\bash.exe"
```

If it prints `True`, Git Bash is installed.

**Step 2: Update the Orbitron config file**

Open `C:\Users\<username>\.orbitron.json` in Notepad or any text editor. Create the file if it doesn't exist.

Change `shell.path` to point to Git Bash:

```diff
  "shell": {
    "args": ["-l"],
-   "path": "/bin/bash"
+   "path": "C:\\Program Files\\Git\\bin\\bash.exe"
  },
```

> ⚠️ Backslashes in JSON paths must be escaped as `\\` (doubled).

**Step 3: Restart Orbitron**

Close the PowerShell window completely, open a new one, and start orbitron again.

### Verify

Ask the AI to run an AWS command:

```
List my AWS S3 buckets
```

If the bucket list appears, the setup is complete.

***

## 🔍 Complete Reinstallation

If all methods fail, completely remove and reinstall:

**Unix/Linux/macOS:**

```bash
# 1. Remove all Orbitron files
rm -rf ~/.local/bin/orbitron*
rm -rf ~/.local/share/orbitron
rm -rf ~/.local/state/orbitron
rm -rf ~/.orbitron

# 2. Restart terminal
exec $SHELL

# 3. Reinstall
curl -fsSL https://orbitron.megaone.com/api/install.sh | bash
```

**Windows:**

```powershell
# 1. Remove all Orbitron files
Remove-Item -Recurse -Force "$env:USERPROFILE\.local\bin\orbitron*"
Remove-Item -Recurse -Force "$env:USERPROFILE\.local\share\orbitron"
Remove-Item -Recurse -Force "$env:USERPROFILE\.local\state\orbitron"
Remove-Item -Recurse -Force "$env:USERPROFILE\.orbitron"

# 2. Restart PowerShell

# 3. Reinstall
irm https://orbitron.megaone.com/api/install.ps1 | iex
```

> 💡 If you want to completely remove Orbitron instead of reinstalling, see the [Complete Uninstall](#complete-uninstall-of-orbitron) section below.

***

## 🗑️ Complete Uninstall of Orbitron

This section explains how to completely remove Orbitron from your system, including configuration, data, and stored secrets.

{% hint style="warning" %}
The order matters. Proceed in this order: **check config files → identify actual data paths → delete**. If you delete the config files first, you won't be able to find any custom data paths.
{% endhint %}

### Step 1: Check for Custom Data Paths

If you ever changed the data directory from its default, that path is recorded in a config file. Check it before deleting the config files:

```bash
# 1) Check the global config for a custom data path
cat ~/.orbitron.json | grep -A2 '"data"'

# Or with jq
jq '.data.directory' ~/.orbitron.json

# 2) Also check per-project local configs (in each project where you used Orbitron)
jq '.data.directory' <project-path>/.orbitron.json
```

Based on the result:

* **Absolute path** → add that path to your deletion list
* **Relative path** (default `.orbitron`) → data was created under each project directory where you ran Orbitron
* **No value** → you only need to delete the default paths below

Additional checks for custom-path users:

* **Even with a custom absolute path**, hooks configuration (`hooks.json`) is always stored in each project's `.orbitron/` directory. Check each project's `.orbitron/` as well.
* **With a custom relative path** (e.g. `mydata`), the MCP cache (`mcp_cache.json`) is created relative to your **home directory** (`~/mydata/`), not the project. Check that directory under your home as well.

### Step 2: Full List of Paths to Delete

| Category                                   | Path                                                  |
| ------------------------------------------ | ----------------------------------------------------- |
| Executable binary (symlink)                | `~/.local/bin/orbitron`                               |
| Versioned binaries                         | `~/.local/share/orbitron/`                            |
| State files (update checks, locks)         | `~/.local/state/orbitron/`                            |
| Global data (global DB, secrets, profiles) | `~/.orbitron/`                                        |
| Global config                              | `~/.orbitron.json`, `~/.orbitron.local.json`          |
| XDG config (if present)                    | `~/.config/orbitron/` or `$XDG_CONFIG_HOME/orbitron/` |
| Install method metadata                    | `~/.local/bin/.orbitron_install_method`               |
| Legacy installations (old versions)        | `~/.orbitron/bin/orbitron`, `/usr/local/bin/orbitron` |
| Per-project data                           | `.orbitron/` and `.orbitron.json` in each project     |

### Step 3: Delete

**Unix/Linux/macOS:**

```bash
# Binary, state files, install metadata
rm -f ~/.local/bin/orbitron ~/.local/bin/.orbitron_install_method
rm -rf ~/.local/share/orbitron
rm -rf ~/.local/state/orbitron

# Global data and config
rm -rf ~/.orbitron
rm -f ~/.orbitron.json ~/.orbitron.local.json
rm -rf ~/.config/orbitron
# If you set a custom XDG_CONFIG_HOME
rm -rf "$XDG_CONFIG_HOME/orbitron"

# Legacy installation (if present)
sudo rm -f /usr/local/bin/orbitron

# Per-project data (in each project where you used Orbitron)
rm -rf <project-path>/.orbitron
rm -f <project-path>/.orbitron.json
```

**Windows:**

```powershell
# Binary, state files
Remove-Item -Recurse -Force "$env:USERPROFILE\.local\bin\orbitron*"
Remove-Item -Force "$env:USERPROFILE\.local\bin\.orbitron_install_method" -ErrorAction SilentlyContinue
Remove-Item -Recurse -Force "$env:USERPROFILE\.local\share\orbitron"
Remove-Item -Recurse -Force "$env:USERPROFILE\.local\state\orbitron"

# Global data and config
Remove-Item -Recurse -Force "$env:USERPROFILE\.orbitron"
Remove-Item -Force "$env:USERPROFILE\.orbitron.json" -ErrorAction SilentlyContinue
Remove-Item -Force "$env:USERPROFILE\.orbitron.local.json" -ErrorAction SilentlyContinue

# Per-project data (in each project where you used Orbitron)
Remove-Item -Recurse -Force "<project-path>\.orbitron"
Remove-Item -Force "<project-path>\.orbitron.json" -ErrorAction SilentlyContinue
```

### Step 4: Remove the PATH Registration (Optional)

**Unix/Linux/macOS**

The installation script prepends the following block to your shell config file. Search for the `# orbitron` comment and remove the block:

```bash
# orbitron
export PATH="$HOME/.local/bin:$PATH"
```

(For fish shell: `fish_add_path $HOME/.local/bin`)

Files to check (depending on your shell):

* `~/.zshrc`, `~/.zshenv`
* `~/.bashrc`, `~/.bash_profile`, `~/.profile`
* `~/.config/fish/config.fish`
* If you use `$XDG_CONFIG_HOME`: `$XDG_CONFIG_HOME/zsh/.zshrc`, `$XDG_CONFIG_HOME/bash/.bashrc`, etc.

**Windows**

On Windows, `%USERPROFILE%\.local\bin` is registered in the **User PATH environment variable in the registry**, not in a shell config file. Run the following in PowerShell to remove it:

```powershell
# Remove the orbitron path from the User PATH
$path = [Environment]::GetEnvironmentVariable("Path", "User")
$newPath = ($path -split ';' | Where-Object { $_ -ne "$env:USERPROFILE\.local\bin" }) -join ';'
[Environment]::SetEnvironmentVariable("Path", $newPath, "User")
```

Alternatively, remove the `%USERPROFILE%\.local\bin` entry from the User `Path` variable via **System Settings > Edit environment variables**.

Only if the registry registration failed, the PATH may have been written to your PowerShell profile instead. Remove the `# Added by orbitron installer` comment and the `$env:Path = ...` line below it from:

* `~\Documents\PowerShell\Microsoft.PowerShell_profile.ps1` (PowerShell 7+)
* `~\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1` (Windows PowerShell 5.x)

### ⚠️ Cautions

* **Delete whole directories, not individual files.** Orbitron uses SQLite in WAL mode, so `orbitron.db-wal` and `orbitron.db-shm` sidecar files exist next to `orbitron.db`. Deleting only the DB file leaves the sidecars behind.
* **Removing API keys completely:** `~/.orbitron/orbitron_global.db` stores encrypted API keys (secrets). If you want a complete removal, deleting the `~/.orbitron/` directory is mandatory.

### If You Don't Remember Your Custom Path

If you already deleted the config files or forgot where you moved the data, search your entire home directory for Orbitron DB files:

```bash
find ~ -name "orbitron.db" -o -name "orbitron_global.db" -o -name "mcp_cache.json" 2>/dev/null
```

Delete the directories containing the files found by the search.

***

## 📝 If You Need Additional Help

If the above solutions don't resolve your issue, please collect the following diagnostic information.

### Quick Information Collection

<details>

<summary>Unix/Linux/macOS - Diagnostic Information Collection Script</summary>

Run the following command in your terminal and copy the results:

```bash
{
  echo "=== Orbitron Diagnostic Information ==="
  echo "Date: $(date)"
  echo ""
  echo "System: $(uname -a)"
  echo ""
  echo "Version: $(orbitron --version 2>&1 | grep -v WARN)"
  echo ""
  echo "Location: $(which orbitron)"
  echo ""
  if [ -L ~/.local/bin/orbitron ]; then
    echo "Symlink: $(readlink ~/.local/bin/orbitron)"
  else
    echo "Symlink: None (regular file)"
  fi
  echo ""
  echo "Version folders:"
  if [ -d ~/.local/share/orbitron/versions/ ]; then
    ls ~/.local/share/orbitron/versions/
  else
    echo "  None (manual installation)"
  fi
  echo ""
  echo "Auto-update: $(orbitron config get autoUpdate 2>&1 | grep -v WARN)"
  echo ""
  if [ -f ~/.local/state/orbitron/last_update_check ]; then
    echo "Last check: $(cat ~/.local/state/orbitron/last_update_check)"
  else
    echo "Last check: No record"
  fi
  echo ""
  echo "Orbitron-related paths in PATH:"
  echo "$PATH" | tr ':' '\n' | grep -E '\.local|orbitron'
  echo ""
  echo "=== Recent Logs ==="
  if [ -f ~/.local/state/orbitron/debug.log ]; then
    tail -n 30 ~/.local/state/orbitron/debug.log
  else
    echo "No log file"
    echo "To generate debug logs, run:"
    echo "  ORBITRON_DEV_DEBUG=true orbitron -d"
  fi
} > ~/orbitron-debug.txt

echo "✅ Information saved to ~/orbitron-debug.txt"
cat ~/orbitron-debug.txt
```

</details>

<details>

<summary>Windows - Diagnostic Information Collection Script</summary>

Run the following in PowerShell and copy the results:

```powershell
$output = "$env:USERPROFILE\Desktop\orbitron-debug.txt"
"=== Orbitron Diagnostic Information ===" | Out-File -FilePath $output -Encoding UTF8
"Date: $(Get-Date -Format 'yyyy-MM-dd HH:mm:ss')" | Out-File -FilePath $output -Append -Encoding UTF8
"" | Out-File -FilePath $output -Append -Encoding UTF8
"System: " | Out-File -FilePath $output -Append -Encoding UTF8 -NoNewline
try {
    (Get-ComputerInfo -ErrorAction Stop).WindowsVersion | Out-File -FilePath $output -Append -Encoding UTF8
} catch {
    "Windows" | Out-File -FilePath $output -Append -Encoding UTF8
}
"" | Out-File -FilePath $output -Append -Encoding UTF8
"Version: " | Out-File -FilePath $output -Append -Encoding UTF8 -NoNewline
try {
    $version = orbitron --version 2>&1 | Select-String -Pattern '^\d+\.\d+\.\d+' | Select-Object -First 1
    if ($version) {
        $version.Line | Out-File -FilePath $output -Append -Encoding UTF8
    } else {
        "Check failed" | Out-File -FilePath $output -Append -Encoding UTF8
    }
} catch {
    "orbitron execution failed" | Out-File -FilePath $output -Append -Encoding UTF8
}
"" | Out-File -FilePath $output -Append -Encoding UTF8
"Location: " | Out-File -FilePath $output -Append -Encoding UTF8 -NoNewline
try {
    where.exe orbitron 2>$null | Out-File -FilePath $output -Append -Encoding UTF8
} catch {
    "Not found" | Out-File -FilePath $output -Append -Encoding UTF8
}
"" | Out-File -FilePath $output -Append -Encoding UTF8
"Installation method metadata: " | Out-File -FilePath $output -Append -Encoding UTF8 -NoNewline
$metadataFile = "$env:USERPROFILE\.local\bin\.orbitron_install_method"
if (Test-Path $metadataFile) {
    Get-Content $metadataFile -ErrorAction SilentlyContinue | Out-File -FilePath $output -Append -Encoding UTF8
} else {
    "None (manual installation)" | Out-File -FilePath $output -Append -Encoding UTF8
}
"" | Out-File -FilePath $output -Append -Encoding UTF8
"Version folders:" | Out-File -FilePath $output -Append -Encoding UTF8
$versionsPath = "$env:USERPROFILE\.local\share\orbitron\versions"
if (Test-Path $versionsPath) {
    Get-ChildItem $versionsPath -ErrorAction SilentlyContinue | ForEach-Object {
        "  $($_.Name)" | Out-File -FilePath $output -Append -Encoding UTF8
    }
} else {
    "  None" | Out-File -FilePath $output -Append -Encoding UTF8
}
"" | Out-File -FilePath $output -Append -Encoding UTF8
"Auto-update: " | Out-File -FilePath $output -Append -Encoding UTF8 -NoNewline
try {
    $autoUpdate = orbitron config get autoUpdate 2>&1 | Select-String -Pattern 'true|false' | Select-Object -First 1
    if ($autoUpdate) {
        $autoUpdate.Line | Out-File -FilePath $output -Append -Encoding UTF8
    } else {
        "Check failed" | Out-File -FilePath $output -Append -Encoding UTF8
    }
} catch {
    "Check failed" | Out-File -FilePath $output -Append -Encoding UTF8
}
"" | Out-File -FilePath $output -Append -Encoding UTF8
"Last check: " | Out-File -FilePath $output -Append -Encoding UTF8 -NoNewline
$checkFile = "$env:USERPROFILE\.local\state\orbitron\last_update_check"
if (Test-Path $checkFile) {
    Get-Content $checkFile -ErrorAction SilentlyContinue | Out-File -FilePath $output -Append -Encoding UTF8
} else {
    "No record" | Out-File -FilePath $output -Append -Encoding UTF8
}
"" | Out-File -FilePath $output -Append -Encoding UTF8
"Pending update: " | Out-File -FilePath $output -Append -Encoding UTF8 -NoNewline
$newExe = "$env:USERPROFILE\.local\bin\orbitron.exe.new"
if (Test-Path $newExe) {
    "Yes (will be applied on next run)" | Out-File -FilePath $output -Append -Encoding UTF8
} else {
    "None" | Out-File -FilePath $output -Append -Encoding UTF8
}
"" | Out-File -FilePath $output -Append -Encoding UTF8
"=== Recent Logs ===" | Out-File -FilePath $output -Append -Encoding UTF8
$logFile = "$env:USERPROFILE\.orbitron\debug.log"
if (Test-Path $logFile) {
    Get-Content $logFile -Tail 30 -ErrorAction SilentlyContinue | Out-File -FilePath $output -Append -Encoding UTF8
} else {
    "No log file" | Out-File -FilePath $output -Append -Encoding UTF8
    "" | Out-File -FilePath $output -Append -Encoding UTF8
    "To generate debug logs, run:" | Out-File -FilePath $output -Append -Encoding UTF8
    "  `$env:ORBITRON_DEV_DEBUG = 'true'" | Out-File -FilePath $output -Append -Encoding UTF8
    "  orbitron -d" | Out-File -FilePath $output -Append -Encoding UTF8
}
Write-Host ""
Write-Host "✅ Information saved to $output" -ForegroundColor Green
Write-Host ""
Get-Content $output
```

</details>

### Generate Debug Logs (If No Logs Exist)

**Unix/Linux/macOS**

```bash
# Run in debug mode
ORBITRON_DEV_DEBUG=true orbitron -d

# Check logs
tail -n 50 ~/.local/state/orbitron/debug.log
```

**Windows**

```powershell
# Run in debug mode
$env:ORBITRON_DEV_DEBUG = "true"
orbitron -d

# Check logs
Get-Content "$env:USERPROFILE\.local\state\orbitron\debug.log" -Tail 50
```

## 🔗 Related Documentation

* [Installation Guide](/orbitron-docs/user-guide/installation.md) - How to install Orbitron
* [Auto-Update Guide](/orbitron-docs/user-guide/installation/auto-update.md) - Auto-update configuration and usage
* [Migration Guide](/orbitron-docs/user-guide/installation/migration-guide.md) - Upgrade from legacy versions