Troubleshooting and limits
What to do when something doesn't work, and the limits Corral has today.
Check your setup
$ corral doctor
$ corral install --check
corral doctor checks the dependencies, the herdr plugin, the theme, Mirador and its browser, and which terminal it detects, one line each, with what to do about each problem. corral install --check prints the installer's checklist, and corral install repairs the installation.
Common problems
| Symptom | What to do |
|---|---|
| The ctrl+b shortcuts do nothing | The herdr plugin runs the compiled corral in Corral's folder, and there is no other version to fall back on. corral doctor shows whether the plugin is linked; corral install repairs the installation. In a clone, build the binary with cargo build --release in rs/. |
| Fresh shows a warning (⚠) about the Wayland clipboard | WSLg doesn't have the clipboard protocol Fresh looks for, so Fresh uses X11, and copy and paste work anyway. Corral starts Fresh without WAYLAND_DISPLAY so it doesn't try; if you open it by hand, use env -u WAYLAND_DISPLAY fresh. |
| The variables pane says "Waiting for the console's session (R or Python)…" or stays empty | That R doesn't have Corral active. In the console's pane, press ctrl+b m, or run corral_activate() in R. |
| The script's shortcuts do nothing, or the editor doesn't take the new theme | That editor was opened with an earlier version. Close it with Ctrl+Q and open the layout again with ctrl+b a. |
corral script --write says the editor didn't answer | The draft has to be open in the editor. An editor opened before you updated Corral needs to be closed (Ctrl+Q) and opened again. |
| No completion | The file has to be saved as .R, and Fresh's status bar has to say LSP (on). If the folder isn't trusted, mark it as trusted from the status bar. |
| Mirador doesn't open | corral doctor shows whether it is running and which browser it uses. corral mirador --url gives the address to open it by hand. If the server doesn't start, its log is in ~/.local/state/corral/mirador.log. |
| ctrl+b enter says "Nothing to send" | Select the code with the mouse (herdr copies it) or copy it with Ctrl+C first. |
| Claude opens its own R instead of using your console | corral eval --check should answer with the console. If it fails, switch Corral on in that R with ctrl+b m. |
| The R console says Ark didn't respond | Ark's log is in ~/.local/state/corral/ark.log. corral config r_console r goes back to plain R while you look into it. |
Known limits
- Corral works on Linux x86_64 and on WSL. It doesn't work on macOS yet: the Rust code talks to the terminal with Linux's values (the
termioslayout and theTIOCGWINSZcode are different on a Mac), Corral looks at processes in/proc, which macOS doesn't have, it opens the browser withxdg-open, and the herdr plugin declares itself for Linux only. - On Windows, plots can't be shown sharply inside herdr, so they go to Mirador (see Plots and Mirador).
- From Warp, Ctrl+Enter, Ctrl+Shift shortcuts and Alt shortcuts don't reach the editor. That is why the main keys are Ctrl+R, F5, Ctrl+L and Ctrl+U.
- Tables from
View()are saved in R's (or Python's) temporary folder and go away when you close the console. - The Python console needs IPython. ctrl+b m on a
pythonwithout IPython marks the pane, but doesn't switch Corral on. - Python figures are saved when they are drawn (PNG and SVG), and Mirador scales them. They aren't drawn again when the window changes size, as httpgd does in R.
- Objects with more than a million elements don't show their size in memory, because computing it after every command would be slow.
- If the herdr server stops (a Windows restart,
wsl --shutdown), the R and Python sessions are lost. herdr restores the panes, but not their memory. - Ark is still a 0.1 version, and Corral talks to its language server over an internal Positron channel (
positron.lsp) that can change between versions. That is whycorral ark --installinstalls the tested version. If a new version fails,corral config r_console rgoes back to plain R. - Debugging with
browser()hasn't been tested with Ark yet. - Ark's console counts every character as one column. With emoji or East Asian characters in a long line, the cursor can end up out of place until the line is drawn again.
- If you restart the Ark console, the editor's completion reconnects when Fresh starts the language server again: close and open the file, or restart Fresh.