# Tern troubleshooting

> Fix common problems with Elide in Tern: installer errors, missing Tern views, plain output where a native view was expected, and inactive links.

Each section names a symptom, then the fix. For the install itself, see [Installation](https://elide.help/docs/tern-install).

## The installer stops

| Message | Fix |
| --- | --- |
| `This preview requires macOS on Apple Silicon.` | The preview runs only on Apple Silicon Macs. |
| `Install Tern and enable its command-line tool before running this installer.` | Put the `tern` command on `PATH`, then rerun `sh ./install.sh`. |
| `Incomplete release: missing executable dist/elide-tern-…` | Unpack the archive again; check it with `shasum -a 256 -c SHA256SUMS` first. |
| `Incomplete release: runtime, SDK, or plugin is missing.` | Same as above. |

## A view does not open

| Message | Fix |
| --- | --- |
| ``The configured runtime has no `elide tern`; update it or set a launcher in plugin/config.json.`` | `runtime` in `plugin/config.json` names an Elide without Tern views. Point it at the release's `../runtime/bin/elide`, or delete the file and rerun `install.sh`. |
| `Configure plugin/config.json before launching a runtime.` | `plugin/config.json` is missing or unreadable; rerun `install.sh`. |
| `Set the embedded SDK directory in plugin/config.json.` | **Open REPL** needs `sdk`; the installer sets it to `../sdk`. |
| `Configure a runtime launcher on this host before opening a remote session.` | Views run on local hosts only. Open the project in a local pane. |
| `Open a local project directory first.` | Focus a pane whose directory is inside an `elide.pkl` project. |
| `No elide.pkl found in this directory or its parents.` | Same as above. |

When Tern's plugin data path is long enough to exceed the Unix socket path limit, set `state` in
`plugin/config.json` to a short private directory.

## A command prints plain text in Tern

| Cause | Fix |
| --- | --- |
| The `elide` on `PATH` has no Tern views | Check `elide tern --help`; it must list `debug`, `project` and `repl`. Install Elide 1.6.3 or newer. |
| Input is not a terminal, or `TERM=dumb` | Expected: the command prints plain text. |
| `--reporter`, `--project`, or a test path that does not exist | Expected: these runs keep the plain output. |
| Output redirected or piped | Expected. |
| `elide build` outside an `elide.pkl` project, or with `--inspect`, `--help` or `--progress` | Expected. |
| `elide serve --no-tui` | Expected. |

The full list is under [Terminal surfaces](https://elide.help/docs/tern-terminal). A warning from `elide test` naming `ELIDE_TERN_SURFACE`
means the variable holds something other than `inline`, `screen` or `auto`; an error naming `--surface` means the
flag does.

## `elide tern` exits with status 2

`elide tern repl|project|debug` hosts views the plugin launches. Outside Tern, `project` and `debug` stop with
`This surface requires Tern` and exit `2`; `repl` falls back to the terminal REPL. Use the plugin's palette commands
instead of running it yourself.

## A link does nothing

`elide://` links open only through the plugin. A dropped link shows a notification naming the reason:

| Notification | Cause |
| --- | --- |
| `Ignored a malformed elide:// link.` | Bad encoding, a repeated key, a fragment, or a path outside its root. |
| `Ignored an elide:// link whose root has no elide.pkl.` | `root` is not a project directory. |
| `Ignored an elide:// link outside a detected project.` | No `root`, and the file is in no project this window has detected. |
| `The linked file does not exist.` | The file was moved or deleted. |
| `elide:// links open on local hosts only.` | The link was clicked in a remote pane. |

Paths are compared as written: a link to `/tmp/x` does not match a project at `/private/tmp/x`.

## The source editor

| Symptom | Cause |
| --- | --- |
| No highlighting | The file has more than 600 lines. |
| A notice instead of the text | The file is over 512 KiB, unreadable or not UTF-8. |
| `Elide source shows JavaScript, TypeScript, Python, Kotlin and Java files.` | Other file types open in Tern's editor. |
| No **Debug** overlay | The file is not JavaScript, TypeScript or Python. |
| No **Diagnostics** overlay | The project has no build report yet; run `elide build` in a Tern terminal. |
| All coverage tints muted, `Coverage measured an older version` | The file changed since the coverage run; run coverage again. |

## Debugging

| Message | Fix |
| --- | --- |
| `Save this file before debugging.` | The debugger runs the file on disk. Save, then launch. |
| `Debugging takes JavaScript, TypeScript or Python sources.` | Pick a supported file, or use the target picker. |
| Controls disabled with `Take control to drive the target` | Another view controls the target; choose **Take control**. |

## See also

- [Troubleshooting](https://elide.help/docs/troubleshooting) for errors outside Tern
- [OpenTelemetry troubleshooting](https://elide.help/docs/opentelemetry/troubleshooting)