How to use this chapter
Look up the symptom, not the feature.
Nearly all of Erya's feedback appears in the last row, so the first thing to do when something goes wrong is read that row to the end. It usually names the cause, and often the key that fixes it.
- Read the last row. Yellow reports, white waits for input, red waits for a decision (see 1.3.6).
- Read row 2. It lists the keys that work right now; if they are not the ones you expect, you are either on another screen or using another profile.
- Press Esc. When you have no idea where you are, it always goes one level back and never breaks anything.
- Press F1. To find the key for a feature, that list is the index.
| Symptom | Section |
|---|---|
| The program will not start | 4.3.2 |
| A file will not open, or opens oddly | 4.3.3 |
| It will not save | 4.3.4 |
| A key does nothing | 4.3.5 |
| The screen is broken, misaligned, or oddly coloured | 4.3.6 |
| Text appears as garbage or question marks | 4.3.7 |
| A whole feature seems to be missing | 4.3.8 |
It will not start
Problems that happen before you ever see Erya's screen.
| What you see | What to do |
|---|---|
| command not found: erya | Not on PATH. Try the full path first; if that runs, it is a PATH problem (1.2.3). |
| Permission denied | chmod +x erya. |
| macOS cannot verify the developer | Quarantine attribute: xattr -d com.apple.quarantine erya (1.2.3). |
| cannot execute binary file | Wrong architecture. Check uname -m (1.2.2). |
| Must run in an interactive terminal | No pipes or redirection. Run it in the terminal (1.2.8). |
| Terminal is too small | At least 24×6; in practice 80×24 (1.2.8). |
| Unsupported option: … | A typo, or a filename starting with a dash — put -- first (1.2.6). |
| … is a directory, not a text file | Pass a file, or browse with Ctrl+O once started (1.2.5). |
The file will not open
Or it opens as something other than you expected.
| Symptom | Cause and fix |
|---|---|
| “Open failed: Permission denied” | No read permission. Check with ls -l, and use sudo if appropriate. |
| It opens empty | The file does not exist. Erya treats an unknown path as a new file and creates it on the first save (1.2.5). Check for a typo. |
| It opens as hexadecimal | The file contains NUL bytes and is treated as binary (3.3.5), or it is a large non-UTF-8 file (3.2.1). |
| “detected unsupported text encoding: UTF-16LE” | UTF-16 and UTF-32 are unsupported. Convert to UTF-8 elsewhere first (3.1.1). |
| The status bar says “Large file read-only” | The file is 64 MiB or larger: readable, not editable (3.2). |
| “report.txt is already open in a tab” | Not an error. Erya switched to the existing tab rather than opening a second copy (2.1.1). |
| Only the first few lines are visible | Scroll. Large files are read on demand (3.2.3). |
It will not save
Saving is where mistakes cost most, so Erya is strict about it.
| Symptom | Cause and fix |
|---|---|
| “Save failed: Permission denied” | The file or its directory is not writable; the atomic save needs to write a temporary file there (2.1.6). |
| “Save failed: No such file or directory” | A directory in the path does not exist; Erya does not create it (2.1.9). |
| “Cannot save a document as a directory” | Save As was given a directory. Add a filename (2.1.5). |
| “Large files use read-only mode and cannot be edited” | This mode has no save (3.2.2). |
| “This binary file is read-only and cannot be changed” | A binary file of 64 MiB or more is streamed and read-only (3.3.8). |
| A red row asks about an external change | Another program changed the file. If unsure press N, then F12 for a copy (2.1.7). |
| “Cannot switch to Big5: …” | The target encoding cannot represent something in the text; Erya refuses rather than damage it (3.1.3). |
A key does nothing
Four possibilities, most likely first.
- The action has no default key. Phrases, macros, block fill and shift, paragraph reflow, and “show cursor position” are all unbound in the default profile (2.4.8, 2.2.6). Press F1 and look for a blank key column.
- You are not on the editing screen. Each screen has its own keys; check row 2 (1.3.3).
- The mode forbids it. Large-file read-only blocks editing actions (3.2.2); the hexadecimal view of a text file is read-only (3.3.1). The message row says which.
- The terminal is not sending it. Most often with Alt combinations and modified arrows (4.1.1). Bind something you can actually press (4.1.4).
Bind the key you are unsure about to something visible — cursor_position prints the cursor location in the message row. If pressing it produces the message, the terminal is delivering the combination.
The screen looks wrong
Usually the terminal rather than Erya.
| Symptom | Cause and fix |
|---|---|
| CJK text does not line up; the cursor drifts | The font is not monospaced, or full-width handling is inconsistent. Use a CJK monospace font (Sarasa, Noto Sans Mono CJK, and similar). |
| Box-drawing characters look wrong | The terminal or font lacks them. Change font, or use a terminal with better coverage. |
| The colours are unpleasant or unreadable | Erya uses the terminal's sixteen colours; the actual shades come from your theme. Adjust the theme. |
| Only one yellow line is visible | The window is below 24×6; enlarge it and everything returns (1.2.8). |
| Leftover artefacts on screen | An unstable SSH connection or a redraw problem. Resizing the window forces a full repaint. |
| Long lines are cut off | Turn on wrapping with Ctrl+L, or scroll with End (2.2.9). |
| The terminal misbehaves after exiting | Erya restores the terminal state normally; if something did go wrong, run reset. |
The text is garbled
First decide whether it is the wrong encoding or a missing glyph.
The whole file is unreadable
The encoding was guessed wrong. Press F7 until it reads correctly, then save (3.1.2). The second-to-last status cell shows what is currently assumed.
Only some characters are boxes or question marks
The terminal font has no glyph for them. The file itself is fine — change font and they appear. Emoji and rare characters are the usual victims.
If the garbling comes from a wrong encoding, saving writes it into the file permanently. Find the right encoding with F7 and check the text before saving. If you cannot, close the tab without saving — the file on disk is still intact.
A whole feature seems missing
With no menus, “I cannot find it” usually means “unbound” or “not supported here”.
| What you are looking for | The actual situation |
|---|---|
| Select all | Does not exist. Use Ctrl+Home then Ctrl+Shift+End (2.2.4). |
| Replace with confirmation | No such mode; use F3 and F5 instead (2.3.4). |
| Replace within a selection | Not supported (2.3.7). |
| Regular-expression search | Not supported; matching is literal (2.3.1). |
| Split view | None. To compare two files, use the comparison view (3.4). |
| Autosave or crash recovery | Neither exists. Only Ctrl+S (1.1.7). |
| Phrases, macros, block fill | They exist, but have no default key (2.4.8). |
| System clipboard integration | Erya's clipboard is internal; use the terminal's copy and paste (2.2.7). |
| Git integration, plug-ins | Neither exists, and neither is planned as part of the scope (1.1.2). |
Still stuck
Include these when you report the problem and it will be resolved much faster.
- The version: the output of erya --version.
- The platform: operating system and version, the architecture from uname -m, and which terminal program you use.
- The key profile: the name shown by F2, or your own keymap.toml.
- The exact message row: copy the whole sentence — it is the single most useful clue.
- The steps: from erya filename onwards, key by key.
- The file: size, encoding, and line endings, all of which the status bar shows.
Before reporting, run with ERYA_KEYMAP= erya or switch back to Erya Terminal Safe with F2 and try again. If the problem disappears, it is about key bindings — which narrows things down enormously.