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 banner across the top of the window

That's a config problem, and Oxide is still running on the last configuration that worked. The banner shows the first line of the error:

• 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 banner clears on the next 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, which hands the file to the OS 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".

No notifications, or clicking one does nothing

• Allow them once. The first notification from the installed app asks for permission; if you dismissed it, turn Oxide on under System Settings → Notifications.
• Development builds. 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

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 banner 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.
• macOS only. A Linux port is mapped out but not written.

Reporting something else

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