Oxide Terminal / docs
Features GitHub Download
Docs / Help / Troubleshooting

Troubleshooting

The things that actually go wrong, and the current limitations worth knowing about before you hit them.

Boxes instead of icons or prompt separators

The powerline separators, git branch marker, and file-tree icons are Nerd Font glyphs. Oxide bundles JetBrainsMono Nerd Font Mono into the binary, so this normally can't happen — but it will if you've pointed font.family at a font without those glyphs.

  • Remove your font.family override to fall back to the bundled font, or
  • install a Nerd Font patched build of the family you want, or
  • drop the glyphs: set tree.icons = false and give prompt.separator / prompt.end plain characters.

A red toast that won't go away

That's a config problem, and Oxide is still running on the last configuration that worked. Errors arrive as red toasts in the bottom-right corner, and unlike other notices they don't fade:

  • config error: … — the TOML didn't parse, or a key isn't recognised. Unknown keys are rejected on purpose, so check for a typo or a key in the wrong section.
  • unknown color preset "…" — the message lists every valid name.
  • keymap: … — one line per bad [keymap] entry: an unknown action id (with a suggestion), a keystroke that doesn't parse, or a bare key in the terminal. The rest of the map is still bound.

Fix the file and save; the toast clears on the next clean reload.

My prompt didn't change

  • Open a new tab. [prompt] and [shell] are baked in when a shell starts; existing shells keep what they had.
  • Check your shell. Prompt injection works for zsh and bash. fish, nushell, and others keep their own prompt entirely.
  • Check prompt.enabled. With it false, Oxide never sets PROMPT.

I use starship / powerlevel10k

Set prompt.enabled = false and leave shell.integration = true. Your prompt is untouched, and you keep the file tree's silent cd and the OSC 133 command markers.

Leaving both on means Oxide's precmd hook runs after your config and overwrites PROMPT — deliberate, but not what you want here.

The tree doesn't follow my cd

Following cd is done by inspecting the PTY's foreground process, so it needs no shell cooperation and works in any shell. Check tree.follow_cwd is true, and remember it follows the focused pane — switching splits re-roots the tree to that shell's directory.

The other direction — c in the tree cd-ing your shell — does need shell.integration = true and zsh or bash.

Opening a file does nothing on fish or csh

Oxide asks the shell which editor to use, so $EDITOR has to be exported rather than set locally. In fish: 

set -gx EDITOR nvim   # -x exports it; plain `set` would not

Without it Oxide falls back to open -t (macOS) or xdg-open (Linux), which hands the file to the desktop's default text editor. zsh and bash users are unaffected either way.

Option doesn't send Meta

Set shell.option_as_meta. macOS doesn't let Oxide tell the two Option keys apart, so "left" and "right" currently behave like "both". On Linux the same setting applies to the Alt keys.

No window on Linux

Oxide renders through Vulkan, so it needs a driver: Mesa's vulkan-radeon or vulkan-intel, or nvidia-utils. vulkaninfo --summary (from vulkan-tools) tells you whether one is loaded. If Wayland is the problem rather than the GPU, WAYLAND_DISPLAY= oxide forces the X11 backend.

No notifications, or clicking one does nothing

  • Allow them once (macOS). The first notification from the installed app asks for permission; if you dismissed it, turn Oxide on under System Settings → Notifications.
  • Have something to receive them (Linux). Notifications go out through notify-send, so libnotify has to be installed and a notification daemon running. Clicking one focuses the pane where the daemon supports actions — mako, dunst, swaync, GNOME, and KDE all do. Nothing to grant.
  • Development builds (macOS). A cargo run binary isn't an app bundle, so macOS won't attach notifications to it; Oxide posts them through osascript instead, and those can't be clicked back into a pane. Run the bundled app from scripts/bundle.sh for the real thing.
  • You were looking at it. By default a command only notifies when its pane wasn't focused or the window wasn't active, and only after notifications.min_duration. Set only_when_unfocused = false or on_failure_always = true to widen that.

Command history is empty

The log is fed by the shell integration's OSC 133 markers, so it needs shell.integration = true and zsh or bash — fish and nushell aren't injected into. It fills in as commands run; nothing is loaded from your shell's history file, and nothing is written anywhere. With commands.emit_cmdline = false Oxide falls back to reading the command line off the grid, which is fine for one-liners and misses edits made with history recall.

The update didn't install

On Linux, nothing installs itself: the top-right pill only opens the release page, and makepkg -si or a fresh tarball's install.sh does the rest. On macOS, updates need Oxide to be able to replace its own bundle. If it lives somewhere you can't write to, or the download was interrupted, the install step fails and leaves the running copy alone. Download the DMG from the releases page and drag it over. Development builds run through cargo run never auto-update; a bundle you built yourself does check, and installing replaces it with the official release build.

Starting from a clean slate

rm -rf ~/.cache/oxide       # generated shell scripts, workspaces, window state, cd/run handoff files
rm ~/.config/oxide/config.toml   # regenerated on next launch

Deleting the cache directory loses pinned workspaces and the remembered window geometry; nothing else. Oxide never writes to your dotfiles, so there is nothing else to undo.

If workspaces.json ever fails to parse, Oxide renames it to workspaces.json.corrupt rather than overwriting it — so a broken file is always recoverable by hand. A file written by an older release is not "corrupt": it's read as-is and copied once to workspaces.json.v<N>.bak before the new format is written over it.

A startup command wedges the app, or never runs

Hold shift while Oxide launches, or run oxide --no-startup-commands, to restore pinned workspaces without running anything; then fix the command with e in the workspaces panel. run_startup_commands = false under [workspaces] turns them off for good.

A command that never runs usually means the shell never showed a prompt inside workspaces.startup_timeout — a toast says so. Raise the timeout if your rc files are slow, or check [shell] program. If it runs but close / restart don't happen, the pane can't see the command end: that needs shell.integration = true and zsh or bash.

Known limitations

  • No IME or dead-key composition. Two-stroke accents and CJK input methods don't work yet.
  • Narrowing a pane can scroll a long prompt's first line off the top. When a line above the cursor wraps during a resize, the terminal core pushes the top row into scrollback rather than using the blank rows below — even on an otherwise empty screen. bash's readline only repaints the last line of a multi-line prompt, so the first line stays out of view until the next prompt is drawn (press enter). Nothing is lost; scroll up and it's there. zsh redraws its whole prompt, so it isn't affected.
  • Pinned workspaces restore layout, not processes. Directories and shape come back with fresh shells; running programs can't survive a quit. A pane's startup command is re-run instead.
  • Left and right Option are indistinguishable — see above.
  • On Linux, bell = "sound" falls back to the visual flash.
  • On Linux, window.titlebar is ignored. The compositor owns decorations: Oxide asks for server-side ones, tiling compositors like Hyprland draw none, and GNOME, which has no server-side decorations, shows the window without a title bar. window.opacity works; window.blur works where the compositor supports it (Hyprland does).
  • On Linux, closing the last window quits Oxide. There's no Dock to bring a fresh one back from.
  • No -e command flag yet, so Oxide can't be an xdg-terminal-exec default terminal on Linux.

Reporting something else

Open an issue on GitHub — Help → Report an Issue on macOS, or Report an Issue in the command palette, goes to the same place. Your Oxide version (Oxide → Check for Updates… or the palette's Check for Updates reports it when you're up to date), your macOS version or distro and compositor, your shell, and the relevant part of your config.toml all help.