par-term 0.30.2

# Troubleshooting

Centralized guide for diagnosing and resolving common issues with par-term. Each issue follows a consistent pattern: symptom, cause, and solution.

## Table of Contents

- [Overview](#overview)
- [Using Debug Logging](#using-debug-logging)
- [Installation Issues](#installation-issues)
  - [macOS Gatekeeper Blocking the App](#macos-gatekeeper-blocking-the-app)
  - [Missing Linux Dependencies](#missing-linux-dependencies)
  - [Build From Source Failures](#build-from-source-failures)
- [Display and Rendering Issues](#display-and-rendering-issues)
  - [Black Screen or No Output](#black-screen-or-no-output)
  - [Font Rendering Problems](#font-rendering-problems)
  - [HiDPI and Scaling Issues](#hidpi-and-scaling-issues)
  - [Inline Graphics Not Displaying](#inline-graphics-not-displaying)
- [Shader Issues](#shader-issues)
  - [Shader Not Loading](#shader-not-loading)
  - [Black or White Screen With Shader](#black-or-white-screen-with-shader)
  - [Text Hard to Read With Shader](#text-hard-to-read-with-shader)
  - [Shader Compilation Errors](#shader-compilation-errors)
  - [Low Frame Rate With Shaders](#low-frame-rate-with-shaders)
  - [Default Cursor Showing Through Cursor Shader](#default-cursor-showing-through-cursor-shader)
  - [Debugging Shaders](#debugging-shaders)
- [Terminal Behavior Issues](#terminal-behavior-issues)
  - [Shell Integration Not Working](#shell-integration-not-working)
  - [Keyboard Shortcuts Not Recognized](#keyboard-shortcuts-not-recognized)
  - [Copy and Paste Issues](#copy-and-paste-issues)
  - [Mouse Behavior Issues](#mouse-behavior-issues)
- [SSH and Remote Issues](#ssh-and-remote-issues)
  - [Hosts Not Appearing in Quick Connect](#hosts-not-appearing-in-quick-connect)
  - [Profile Not Auto-Switching on SSH](#profile-not-auto-switching-on-ssh)
  - [mDNS Hosts Not Appearing](#mdns-hosts-not-appearing)
  - [Shell Integration on Remote Hosts](#shell-integration-on-remote-hosts)
- [Performance Issues](#performance-issues)
  - [High CPU Usage](#high-cpu-usage)
  - [Slow Rendering](#slow-rendering)
  - [High Memory Usage](#high-memory-usage)
- [Configuration Issues](#configuration-issues)
  - [Config Not Loading](#config-not-loading)
  - [Settings Not Saving](#settings-not-saving)
  - [Profile Switching Issues](#profile-switching-issues)
  - [Arrangement Restore Issues](#arrangement-restore-issues)
- [Update Issues](#update-issues)
  - [Self-Update Refused](#self-update-refused)
  - [Platform Binary Not Found](#platform-binary-not-found)
  - [Update Failed Network Error](#update-failed-network-error)
  - [Permission Denied During Update](#permission-denied-during-update)
  - [Updated App Blocked by Gatekeeper](#updated-app-blocked-by-gatekeeper)
  - [Old Version Still Running After Update](#old-version-still-running-after-update)
- [Getting Help](#getting-help)
- [Related Documentation](#related-documentation)

## Overview

This guide covers the most common issues encountered when installing, configuring, and using par-term. For each issue, the **Symptom** describes what you observe, the **Cause** explains why it happens, and the **Solution** provides actionable steps to fix it.

Before diving into specific issues, enable debug logging -- it is the primary diagnostic tool for most problems.

## Using Debug Logging

par-term writes debug logs to a file rather than the terminal, so logging never interferes with your session.

**Log file location:**

| Platform | Path |
|----------|------|
| macOS/Linux | `$TMPDIR/par_term_debug.log` (defaults to `/tmp/`) |
| Windows | `%TEMP%\par_term_debug.log` |

**Enabling debug logging:**

```bash
# Via command-line flag (highest priority)
par-term --log-level debug

# Via environment variable (also mirrors to stderr)
RUST_LOG=debug par-term

# Via config file (~/.config/par-term/config.yaml)
log_level: debug
```

**Log levels** (from least to most verbose): `off`, `error`, `warn`, `info`, `debug`, `trace`

**Monitoring logs in real time:**

```bash
tail -f /tmp/par_term_debug.log
```

**Filtering logs by component:**

```bash
tail -f /tmp/par_term_debug.log | grep --line-buffered "shader"
tail -f /tmp/par_term_debug.log | grep --line-buffered "terminal"
tail -f /tmp/par_term_debug.log | grep --line-buffered "renderer"
```

**Capturing logs for a bug report:**

```bash
# Start with trace logging, reproduce the issue, then exit
par-term --log-level trace

# Copy the log file
cp /tmp/par_term_debug.log ~/Desktop/par-term-debug.log
```

The Settings UI also provides debug logging controls under **Settings > Advanced > Debug Logging**, including a log level dropdown, log file path display, and an Open Log File button. Changes take effect immediately without restarting.

> **Note:** Some internal components use custom `debug_*!()` macros controlled by the `DEBUG_LEVEL` environment variable (separate from `log_level`). Set `DEBUG_LEVEL=4` for maximum custom debug output.

## Installation Issues

### macOS Gatekeeper Blocking the App

**Symptom:** macOS reports that par-term "is damaged and can't be opened" or shows an "unidentified developer" warning.

**Cause:** macOS applies a quarantine attribute to binaries downloaded from the internet. Since par-term release binaries are not notarized with an Apple Developer ID, Gatekeeper blocks execution.

**Solution:**

Remove the quarantine attribute:

```bash
# For the release binary
xattr -cr target/release/par-term

# For the .app bundle
xattr -cr /Applications/par-term.app
```

> **Note:** The Homebrew cask install (`brew install --cask paulrobello/tap/par-term`) handles this automatically.

### Missing Linux Dependencies

**Symptom:** Build errors or runtime crashes on Linux related to missing libraries (GTK, X11, Wayland, XCB, audio).

**Cause:** par-term requires GTK3 and X11/Wayland libraries for window management and display.

**Solution:**

Install the required packages for your distribution:

**Ubuntu/Debian:**

```bash
sudo apt install libgtk-3-dev libxkbcommon-dev libwayland-dev libxcb-render0-dev libxcb-shape0-dev libxcb-xfixes0-dev libasound2-dev
```

**Fedora/RHEL:**

```bash
sudo dnf install gtk3-devel libxkbcommon-devel wayland-devel libxcb-devel alsa-lib-devel
```

**Arch Linux:**

```bash
sudo pacman -S gtk3 libxkbcommon wayland libxcb alsa-lib
```

### Build From Source Failures

**Symptom:** Compilation errors when running `cargo build` or `make build`.

**Cause:** Missing Rust toolchain, outdated compiler version, or missing system dependencies.

**Solution:**

1. Ensure you have Rust 1.85+ installed (2024 edition required):

   ```bash
   rustup update stable
   rustc --version
   ```

2. On Linux, install the required system dependencies listed in [Missing Linux Dependencies](#missing-linux-dependencies).

3. Ensure modern graphics drivers are installed (Vulkan on Linux, Metal on macOS, DirectX 12 on Windows).

4. Clean and rebuild:

   ```bash
   cargo clean
   cargo build --release
   ```

## Display and Rendering Issues

### Black Screen or No Output

**Symptom:** The terminal window opens but displays a black screen with no text or cursor.

**Cause:** GPU driver incompatibility, missing graphics backend, or wgpu initialization failure.

**Solution:**

1. Update your graphics drivers to the latest version.
2. Check the debug log for GPU-related errors:

   ```bash
   par-term --log-level debug
   grep -i "wgpu\|gpu\|surface\|adapter" /tmp/par_term_debug.log
   ```

3. On Linux, verify Vulkan support:

   ```bash
   vulkaninfo --summary
   ```

4. If using a virtual machine or remote desktop, ensure GPU passthrough or software rendering is available.

### Font Rendering Problems

**Symptom:** Characters appear as blank squares (tofu), fonts look blurry, or incorrect glyphs display.

**Cause:** Missing fonts, font fallback chain not finding the correct glyphs, or font hinting settings.

**Solution:**

1. Ensure your configured font is installed on the system. par-term defaults to a built-in font if the configured one is not found.
2. Toggle font hinting in **Settings > Appearance > Font Hinting** -- enabling hinting improves sharpness at common sizes.
3. Install a Nerd Font for icon support in the tab bar and profile picker.
4. Check font-related messages in the debug log:

   ```bash
   par-term --log-level debug
   grep -i "font\|glyph\|shap" /tmp/par_term_debug.log
   ```

### HiDPI and Scaling Issues

**Symptom:** UI elements appear too large, too small, or incorrectly scaled on high-DPI displays.

**Cause:** Pixel-dimension config values or window positions not scaling correctly for the display's DPI factor.

**Solution:**

1. Ensure your operating system's display scaling is configured correctly.
2. par-term auto-detects the display scale factor. If text or UI elements appear incorrect, try adjusting the font size in **Settings > Appearance**.
3. For multi-monitor setups with mixed DPI values, par-term stores window positions in logical pixels and applies per-monitor DPI conversion automatically. If positions seem off, save and restore a window arrangement to recalibrate.

### Inline Graphics Not Displaying

**Symptom:** Sixel, iTerm2, or Kitty inline images do not appear in the terminal.

**Cause:** The graphics protocol is not enabled, the image data is too large, or the terminal is in split-pane mode with an older version.

**Solution:**

1. Verify inline graphics support is enabled -- par-term supports Sixel, iTerm2, and Kitty protocols by default.
2. Ensure the image data is valid. Test with a known working image:

   ```bash
   # iTerm2 protocol test
   printf '\033]1337;File=inline=1;size=%d:%s\a' "$(wc -c < image.png)" "$(base64 < image.png)"
   ```

3. Check the debug log for graphics-related messages:

   ```bash
   par-term --log-level debug
   grep -i "sixel\|iterm\|kitty\|graphic\|image" /tmp/par_term_debug.log
   ```

## Shader Issues

par-term has two separate shader systems -- **background shaders** (`custom_shader`) and **cursor shaders** (`cursor_shader`). When debugging one type, temporarily disable the other to isolate the issue.

### Shader Not Loading

**Symptom:** No visual effect after enabling a shader.

**Cause:** Shader file not found, shader not enabled in config, or configuration not reloaded.

**Solution:**

1. Verify the shader file exists in `~/.config/par-term/shaders/`
2. Check that `custom_shader_enabled: true` is set in your config
3. Press `F5` to reload configuration
4. Check the debug log for shader loading errors

### Black or White Screen With Shader

**Symptom:** Terminal content becomes invisible after enabling a shader.

**Cause:** The shader is not outputting correct alpha values or UV coordinates are out of range.

**Solution:**

1. Ensure `fragColor.a = 1.0` for opaque output in your shader
2. Verify UV coordinates are in the 0.0 to 1.0 range
3. Check that `texture(iChannel4, uv)` is sampling terminal content correctly
4. Try switching to background-only mode: `custom_shader_full_content: false`

### Text Hard to Read With Shader

**Symptom:** Text is blurry, distorted, or the shader background is too bright to read against.

**Cause:** Full-content mode distorting text, text opacity too low, or shader brightness too high.

**Solution:**

1. Use background-only mode: set `custom_shader_full_content: false`
2. Increase text opacity: `custom_shader_text_opacity: 1.0`
3. Lower shader brightness: `custom_shader_brightness: 0.3` (range: 0.05 to 1.0)
4. Reduce effect intensity within the shader code itself

### Shader Compilation Errors

**Symptom:** Error messages in the log about GLSL compilation failures.

**Cause:** Incompatible GLSL syntax or unsupported constructs.

**Solution:**

Common GLSL fixes:

- Use `texture()` not `texture2D()`
- Declare constants with the `const` keyword
- Use proper array syntax: `vec3[N] arr = vec3[N](...)`
- Do not include a `#version` directive (par-term adds it automatically)
- Expand `mat2(vec4)` to `mat2(v.x, v.y, v.z, v.w)` for GLSL 450 compatibility

Check the transpiled output for details -- see [Debugging Shaders](#debugging-shaders).

### Low Frame Rate With Shaders

**Symptom:** Stuttering or choppy animation when shaders are active.

**Cause:** Shader complexity exceeds GPU capacity at the target frame rate.

**Solution:**

1. Reduce shader complexity (fewer loops, simpler math)
2. Lower animation speed: `custom_shader_animation_speed: 0.5`
3. Disable animation entirely: `custom_shader_animation: false`
4. Enable power saving: `pause_shaders_on_blur: true` to pause animations when the window loses focus

### Default Cursor Showing Through Cursor Shader

**Symptom:** The default block/beam cursor is visible behind or through your cursor shader effect.

**Cause:** The renderer is drawing the default cursor in addition to the cursor shader.

**Solution:**

Set `cursor_shader_hides_cursor: true` in your config. This tells the renderer to skip drawing the default cursor when a cursor shader is active. Recommended for shaders that fully replace the cursor appearance.

### Debugging Shaders

par-term writes intermediate shader files for debugging. Paths use the OS temp directory (`$TMPDIR` on macOS/Linux, `%TEMP%` on Windows):

| File | Description |
|------|-------------|
| `/tmp/par_term_<shader_name>_shader.wgsl` | Transpiled WGSL output for each shader (hardcoded `/tmp/`) |
| `<temp_dir>/par_term_debug_wrapped.glsl` | Wrapped GLSL input sent to the transpiler (last shader processed) |
| `<temp_dir>/par_term_debug_wrapped_source.glsl` | Raw GLSL source before wrapping (last shader processed) |

Enable `shader_hot_reload: true` in your config for faster iteration during shader development. Set `shader_hot_reload_delay: 100` (milliseconds) for the debounce interval.

## Terminal Behavior Issues

### Shell Integration Not Working

**Symptom:** Directory tracking, prompt navigation, or command notifications do not work. Tab titles do not update to show the current directory.

**Cause:** Shell integration script not installed, not sourced, or the shell session was not restarted after installation.

**Solution:**

1. Install shell integration:

   ```bash
   par-term install-shell-integration
   ```

   Or open **Settings > Integrations** and click **Install Shell Integration**.

2. Restart your shell or source the RC file:

   ```bash
   source ~/.bashrc    # bash
   source ~/.zshrc     # zsh
   ```

3. Verify the integration script exists:

   ```bash
   ls ~/.config/par-term/shell_integration.*
   ```

4. Check that your shell RC file contains the source line:

   ```bash
   # >>> par-term shell integration >>>
   [ -f "$HOME/.config/par-term/shell_integration.bash" ] && source "$HOME/.config/par-term/shell_integration.bash"
   # <<< par-term shell integration <<<
   ```

5. If reinstalling, uninstall first:

   ```bash
   par-term uninstall-shell-integration
   par-term install-shell-integration
   ```

### Keyboard Shortcuts Not Recognized

**Symptom:** Keybindings do not trigger the expected action, or modifier keys seem wrong.

**Cause:** On Linux/Windows, par-term uses `Ctrl+Shift` modifiers (not plain `Ctrl`) for most shortcuts to avoid conflicts with terminal control codes like `Ctrl+C`. macOS uses `Cmd`.

**Solution:**

1. Check the correct modifier for your platform:
   - **macOS**: `Cmd` for most shortcuts
   - **Linux/Windows**: `Ctrl+Shift` for most shortcuts
2. Review your keybindings in **Settings > Input > Keybindings**
3. See [KEYBOARD_SHORTCUTS.md](KEYBOARD_SHORTCUTS.md) for the complete shortcut reference
4. Custom keybindings in `config.yaml` override defaults -- check for conflicts

### Shift+Letter Produces Lowercase in crossterm Apps (macOS/Linux)

**Symptom:** On macOS or Linux, pressing `Shift+a` inside a crossterm-based application (e.g. Claude Code, Ratatui TUIs) produces lowercase `a` instead of `A`.

**Cause:** The application sets modifyOtherKeys mode 2, which caused par-term to encode `Shift+a` as `CSI 27;2;97~`. Crossterm receives this event as `KeyEvent { code: Char('a'), modifiers: SHIFT }` but does not apply the SHIFT modifier to uppercase the character.

**Solution:**

Update to par-term v0.30.1+ — shift-only alphabetic key combinations are now exempted from modifyOtherKeys mode-2 encoding (matching the existing mode-1 exemption), allowing the logical-key path to send `'A'` directly.

### Windows Modifier Keys Break After Notification

**Symptom:** On Windows, after a toast notification or popup briefly steals focus, `Shift`, `Ctrl`, or `Alt` stop working or behave incorrectly until the key is physically re-pressed.

**Cause:** `WM_NCACTIVATE(false)` fires when a notification becomes active, causing winit to emit `ModifiersChanged(empty)`. Because keyboard focus is never actually lost, no `WM_SETFOCUS` fires to restore state.

**Solution:**

1. Press and release the broken modifier key once to resynchronize state
2. Update to par-term v0.30.0+ — modifier state is now synthesized directly from physical `KeyboardInput` events as a fallback, preventing permanent breakage

### Copy and Paste Issues

**Symptom:** `Cmd+V` or `Ctrl+V` does not paste, or copied text is empty.

**Cause:** On macOS, the system menu accelerators (muda) intercept `Cmd+V/C/A` before the terminal processes them. Clicking the window to focus it can clear the clipboard selection.

**Solution:**

1. Ensure you are using the correct shortcut for your platform (`Cmd+C/V` on macOS, `Ctrl+Shift+C/V` on Linux/Windows)
2. If paste does not work in the settings window, par-term injects paste events directly -- this is handled automatically
3. For clipboard images, `Cmd+V` forwards to the terminal when the clipboard contains an image but no text
4. If focus-clicking clears your clipboard, this is a known mitigation where the first mouse click that focuses the window is suppressed

### Text Selection Highlight Stays Fixed While Scrolling

**Symptom:** After making a text selection and then scrolling, the highlight remains frozen at its original visual position on screen while the selected content scrolls out of view.

**Cause:** In versions before v0.30.1, selection coordinates were stored as viewport-relative rows with no record of the scroll offset at capture time. After scrolling, the highlight tested the original viewport rows, freezing it visually.

**Solution:**

Update to par-term v0.30.1+ — `Selection` now records the scroll offset at capture time, and the renderer adjusts the highlighted rows by the offset delta before drawing. This applies to normal, line, and rectangular selection modes in both single-pane and split-pane layouts.

### Mouse Behavior Issues

**Symptom:** Mouse clicks or scroll events behave unexpectedly, or text selection triggers accidentally on trackpad.

**Cause:** Applications running in the terminal may capture mouse events (mouse tracking mode). Trackpad jitter can cause micro-selections.

**Solution:**

1. To select text when an application has mouse tracking enabled, hold `Shift` while clicking or dragging to bypass the application's mouse capture
2. par-term includes a drag dead-zone to suppress accidental micro-selections from trackpad jitter
3. Check mouse-related settings in **Settings > Input > Mouse**

## SSH and Remote Issues

### Hosts Not Appearing in Quick Connect

**Symptom:** The SSH Quick Connect dialog (`Cmd+Shift+S` / `Ctrl+Shift+S`) shows no hosts or is missing expected entries.

**Cause:** SSH config file is missing or contains only wildcard entries, known_hosts is unreadable, or mDNS is not enabled.

**Solution:**

1. Verify `~/.ssh/config` exists and contains valid `Host` entries (not just `Host *` wildcards)
2. Check that `~/.ssh/known_hosts` is readable
3. For network-discovered hosts, enable mDNS in **Settings > Integrations > SSH > mDNS/Bonjour Discovery** or set `enable_mdns_discovery: true` in config

### Profile Not Auto-Switching on SSH

**Symptom:** Connecting to a remote host does not trigger automatic profile switching.

**Cause:** Auto-switch is disabled, profile hostname patterns do not match, or shell integration is not installed on the remote host.

**Solution:**

1. Ensure `ssh_auto_profile_switch: true` in your config
2. Verify the profile has `hostname_patterns` that match the remote hostname
3. Install shell integration on the remote host for OSC 1337 hostname reporting (see [Shell Integration on Remote Hosts](#shell-integration-on-remote-hosts))

### mDNS Hosts Not Appearing

**Symptom:** Local network SSH hosts are not discovered in the Quick Connect dialog.

**Cause:** mDNS discovery is disabled, scan timeout is too short, or remote hosts do not advertise the SSH service.

**Solution:**

1. Enable mDNS in **Settings > Integrations > SSH > mDNS/Bonjour Discovery** or set `enable_mdns_discovery: true`
2. Increase `mdns_scan_timeout_secs` for slower networks (range: 1 to 10 seconds)
3. Ensure remote hosts advertise `_ssh._tcp` via Bonjour (macOS) or Avahi (Linux)

### Shell Integration on Remote Hosts

**Symptom:** Directory tracking and prompt navigation do not work in SSH sessions.

**Cause:** Shell integration is only installed locally and needs to be installed on each remote host separately.

**Solution:**

1. From the menu bar while connected to a remote host: **Shell > Install Shell Integration on Remote Host...**
2. Or run manually in the SSH session:

   ```bash
   curl -sSL https://paulrobello.github.io/par-term/install-shell-integration.sh | sh
   ```

3. Restart the remote shell after installation for changes to take effect
4. Requirements: `curl` must be available on the remote host and you need write permission to modify shell RC files

## Performance Issues

### High CPU Usage

**Symptom:** par-term consumes excessive CPU even when idle.

**Cause:** Animated shaders rendering continuously, high refresh rate, or frequent terminal redraws.

**Solution:**

1. Enable power saving when the window is not focused:

   ```yaml
   pause_shaders_on_blur: true
   pause_refresh_on_blur: true
   unfocused_fps: 30
   ```

2. Disable animated shaders if not needed: `custom_shader_animation: false`
3. Reduce animation speed: `custom_shader_animation_speed: 0.5`
4. Check if a background process in the terminal is producing continuous output

### Slow Rendering

**Symptom:** Visible lag when scrolling, typing, or resizing the terminal.

**Cause:** Complex shaders, large scrollback buffer, or GPU driver performance.

**Solution:**

1. Reduce shader complexity or disable shaders temporarily to isolate the cause
2. Update GPU drivers to the latest version
3. Check the debug log for rendering bottlenecks:

   ```bash
   par-term --log-level debug
   grep -i "render\|frame\|fps" /tmp/par_term_debug.log
   ```

### High Memory Usage

**Symptom:** par-term memory usage grows over time.

**Cause:** Large scrollback buffers, many open tabs, or cached inline graphics.

**Solution:**

1. Reduce the scrollback buffer size in **Settings > Terminal > Scrollback Lines**
2. Close unused tabs
3. Large inline images are cached in RGBA texture memory -- closing tabs with many inline images frees this memory

## Configuration Issues

### Config Not Loading

**Symptom:** Settings revert to defaults on startup, or config changes have no effect.

**Cause:** Config file is missing, has syntax errors, or is in the wrong location.

**Solution:**

1. Verify the config file location:
   - **macOS/Linux**: `~/.config/par-term/config.yaml`
   - **Windows**: `%APPDATA%\par-term\config.yaml`

2. Check for YAML syntax errors. A common issue is incorrect indentation or missing quotes:

   ```bash
   # Validate YAML syntax
   python3 -c "import yaml; yaml.safe_load(open('$HOME/.config/par-term/config.yaml'))"
   ```

3. Press `F5` to reload the configuration without restarting par-term
4. Check the debug log for config-related errors:

   ```bash
   par-term --log-level debug
   grep -i "config\|yaml\|parse" /tmp/par_term_debug.log
   ```

### Settings Not Saving

**Symptom:** Changes made in the Settings UI revert after closing or restarting par-term.

**Cause:** The settings were not explicitly saved, or the config file is not writable.

**Solution:**

1. In the Settings UI, ensure you click **Save** after making changes
2. Verify the config directory is writable:

   ```bash
   ls -la ~/.config/par-term/
   ```

3. Check that no other process has the config file locked

### Profile Switching Issues

**Symptom:** Profiles do not apply correctly, or the wrong profile activates.

**Cause:** Profile order matters for auto-switching (first match wins), or directory patterns do not match the current path.

**Solution:**

1. Check profile order in **Settings > Profiles** -- the first matching profile wins
2. For directory-based switching, verify patterns use correct glob syntax:
   - Patterns support `~` for home directory expansion
   - Pattern matching is case-sensitive
3. Directory switching requires shell integration for OSC 7 CWD tracking
4. Profiles are stored in `~/.config/par-term/profiles.yaml`

### Arrangement Restore Issues

**Symptom:** Restoring a window arrangement places windows on the wrong monitor, or tabs appear with incorrect properties.

**Cause:** Monitor layout has changed since the arrangement was saved, or the arrangement file is corrupted.

**Solution:**

1. par-term maps saved monitors to current monitors by name first, then by index, and falls back to the primary monitor. If your monitor configuration has changed, windows may land on a different display.
2. Window positions are clamped to ensure at least 100 pixels remain visible -- if a window appears in an unexpected position, this clamping moved it onto the visible area.
3. Save a new arrangement to capture the current monitor layout.
4. Arrangements are stored in:
   - **macOS/Linux**: `~/.config/par-term/arrangements.yaml`
   - **Windows**: `%APPDATA%\par-term\arrangements.yaml`

## Update Issues

### Self-Update Refused

**Symptom:** Running `par-term self-update` displays a message about Homebrew or cargo installation and refuses to update.

**Cause:** par-term detected that it was installed via a package manager (Homebrew or cargo) and will not perform in-place updates to avoid inconsistencies with the package manager's tracking.

**Solution:**

Use the appropriate package manager command:

```bash
# Homebrew
brew upgrade --cask par-term

# Cargo
cargo install par-term
```

### Platform Binary Not Found

**Symptom:** Error: "Could not find par-term-<platform> in the latest release"

**Cause:** The latest GitHub release does not contain a binary for your OS and architecture.

**Solution:**

Check the [releases page](https://github.com/paulrobello/par-term/releases) for supported platforms. If your platform is not listed, build from source.

### Update Failed Network Error

**Symptom:** Error: "Failed to fetch release info"

**Cause:** Network connectivity issue or GitHub API rate limit.

**Solution:**

1. Check your internet connection
2. Try again later -- GitHub enforces API rate limits
3. par-term enforces a minimum one-hour interval between API requests to avoid rate limiting

### Permission Denied During Update

**Symptom:** Error: "Failed to replace binary: Permission denied"

**Cause:** The running process does not have write access to its installation directory.

**Solution:**

On Linux, if the binary is in a system directory (e.g., `/usr/local/bin/`), you may need elevated permissions. Consider installing to a user-writable location or using a package manager instead.

### Updated App Blocked by Gatekeeper

**Symptom:** After updating, macOS reports the app "is damaged and can't be opened."

**Cause:** macOS quarantine attributes were applied to the downloaded update. The self-updater normally strips these via `xattr -cr`, but this can fail if the update was interrupted.

**Solution:**

```bash
xattr -cr /Applications/par-term.app
```

If the problem persists, verify that the binary is not corrupted by comparing its checksum against the release asset on the [GitHub releases page](https://github.com/paulrobello/par-term/releases).

### Old Version Still Running After Update

**Symptom:** After a successful update, `par-term --version` still shows the old version.

**Cause:** The update replaces the binary on disk, but the running process continues using the old version until restarted.

**Solution:**

Close and reopen par-term. A restart is required after every update to use the new version.

## Getting Help

If the solutions in this guide do not resolve your issue:

1. **Collect diagnostic information:**
   - Start par-term with `--log-level trace`
   - Reproduce the issue
   - Copy `/tmp/par_term_debug.log` for your bug report

2. **Include system information:**
   - Operating system and version
   - GPU model and driver version
   - par-term version (`par-term --version`)
   - Installation method (Homebrew, cargo, standalone binary, app bundle)

3. **Config file location:**
   - **macOS/Linux**: `~/.config/par-term/config.yaml`
   - **Windows**: `%APPDATA%\par-term\config.yaml`

4. **Report bugs** on GitHub Issues: [https://github.com/paulrobello/par-term/issues](https://github.com/paulrobello/par-term/issues)

## Related Documentation

- [Debug Logging](LOGGING.md) - Full logging configuration and module filtering
- [Custom Shaders Guide](CUSTOM_SHADERS.md) - Shader creation, uniforms, and debugging
- [Integrations](INTEGRATIONS.md) - Shell integration installation and management
- [SSH Host Management](SSH.md) - SSH profiles, discovery, and auto-switching
- [Profiles](PROFILES.md) - Profile system, auto-switching, and storage
- [Arrangements](ARRANGEMENTS.md) - Window layout save and restore
- [Self-Update](SELF_UPDATE.md) - Update checking, installation types, and CLI usage
- [Keyboard Shortcuts](KEYBOARD_SHORTCUTS.md) - Complete keybinding reference
- [Content Prettifier](PRETTIFIER.md) - Content detection and rendering configuration
- [Architecture Overview](ARCHITECTURE.md) - System design and component overview