Troubleshooting
Use Red's focused checks to separate installation, configuration, runtime asset, language-server, Agent, keyboard, and recovery problems.
Start with the narrow check
| Problem | First check |
|---|---|
| Red doesn't start or bundled tools are missing | red --self-check |
| Configuration fails to load | red --check-config |
| A plugin or theme looks stale or missing | red --runtime-files |
| Codex can't start from Red | red --agent-check --strict |
| A modified Enter shortcut doesn't arrive | red keys |
| A language server doesn't respond | Confirm its executable is on PATH, then reopen a matching file |
| A previous editor stopped with unsaved work | red --resume |
Read messages and logs
Press Space m or run :messages to see problems that need your attention, such as a failed save, a file changed on disk, or a disabled plugin. Each item's details give the next step, and it clears once the problem is fixed. From Red v0.10.0, routine feedback stays in the status line, and shell and update output appear in :jobs. Red writes red.log in its configuration directory by default. Relative log_file paths are resolved from that directory.
Fix common problems
- Command not found after installation: open a new terminal or add the install directory printed by the installer to
PATH. - Language tools are empty: install the configured server executable. Buffer-word completion still works without a server.
- A bundled theme or plugin behaves like an older copy: a file in your configuration directory may be shadowing the embedded asset. Check
red --runtime-files, then remove or replace the ejected copy. - An Agent prompt failed to start: update Codex, run
codex login, then retry the preserved prompt. - Shift+Enter behaves like Enter: use Ctrl+J for a newline and run
red keysto see what the terminal sends. - A dirty file changed on disk: run :diffdisk; use :e!, :w file, or :w! only after choosing which version to keep.
- Detach isn't available on Windows: use
red --resumefor crash recovery. Live detach and attach currently require macOS or Linux.
Report a reproducible problem
Include your Red version, operating system, terminal, the smallest reproduction, and the relevant focused-check output. Remove private paths, source, prompts, and credentials before sharing logs.