# Troubleshooting

Canonical HTML: [Troubleshooting](https://getred.dev/docs/troubleshooting). Website source: `b212874eefaf200143affa21c770fbb8855a4f5c`. Documented Red release: v0.9.1. Installer source: `b86a2ca4b92e9547d3b174910c82db8a259f5171`.

Use Red's focused checks to separate installation, configuration, runtime asset, language-server, Agent, keyboard, and recovery problems.

<a id="start-with-the-narrow-check"></a>

## 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`                                                   |

<a id="read-messages-and-logs"></a>

## Read messages and logs

Press `Space m` or run `:messages` to browse editor notifications, command output, and recent errors. Red writes `red.log` in its configuration directory by default. Relative `log_file` paths are resolved from that directory.

<a id="fix-common-problems"></a>

## 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 keys` to 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 --resume` for crash recovery. Live detach and attach currently require macOS or Linux.

<a id="report-a-reproducible-problem"></a>

## 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.

[Open a GitHub issue](https://github.com/codersauce/red/issues)