# Debugging

> Debug Elide programs: read plain error output, attach a debugger, measure coverage, profile CPU time, trace with Insights scripts, and report a bug.

Find and report problems in programs run with Elide.

## Read errors

```bash
elide --error-format=plain run app.js
```

Plain errors go to stderr with a short stack; program output stays on stdout. `--verbose` or `--debug` adds Elide's
own logs.

<img src="https://elide.help/assets/demos/errors.gif" alt="Viewing an uncaught program error in Elide" width="1591" height="946" loading="lazy" decoding="async" class="rounded-lg border border-border my-6 w-full" />

| Flag | Effect |
| --- | --- |
| `--abort-on-uncaught-exception` | Print the error, then raise `SIGABRT` (exit `134`) so the OS writes a core dump. |
| `--redirect-warnings=FILE` | Write process warnings, such as `process.emitWarning()`, to `FILE`, not stderr. |
| `--timeout=DURATION` | Stop the program after `DURATION` (for example `30s`) with exit `124`. |
| `--max-mem=SIZE` | Limit the heap size, for example `512m`. Exceeding it fails with a nonzero exit. |

<img src="https://elide.help/assets/demos/debug.gif" alt="elide --profiler and --debugger — profiler report and debug endpoints" width="1591" height="618" loading="lazy" decoding="async" class="rounded-lg border border-border my-6 w-full" />

## Attach a debugger

| Program | Flag | Listens on | Client |
| --- | --- | --- | --- |
| JavaScript, TypeScript, Python | `--debugger=cdp` | `ws://127.0.0.1:1337/…` | Chrome DevTools or any CDP client |
| JavaScript, TypeScript, Python | `--debugger=dap` | `127.0.0.1:4711`, waits for a client | Any DAP-capable editor |
| Java, Kotlin | `--debugger` | `127.0.0.1:5005` (JDWP), suspended | IntelliJ IDEA, VS Code, `jdb` |

```bash
elide run --debugger=cdp app.js
```

```text
Debugger listening on ws://127.0.0.1:1337/<id>/inspect
For help, see: https://docs.elide.dev/guides/debugging
E.g. in Chrome open: devtools://devtools/bundled/js_app.html?ws=127.0.0.1:1337/<id>/inspect
```

Open the `devtools://` link in Chrome.

```bash
elide run --debugger=dap app.js
elide run --debugger Hello.kt
```

```text
Listening for transport dt_socket at address: 5005
```

Change a listener's address with `--debugger-host` and `--debugger-port`:

```bash
elide run --debugger=dap --debugger-port=5678 app.js
elide run --debugger=0.0.0.0:5005 Hello.kt
```

A number or `host:port` after `--debugger` is a JDWP address and applies to Java and Kotlin only. JDWP has no
authentication: bind beyond loopback only on a trusted network, or use an SSH tunnel.

### Debug tests

```bash
elide test --debugger
elide test --debugger=dap sample.test.mts
elide test --debugger=5005
```

| Flag | Debugs |
| --- | --- |
| `--debugger` | JavaScript tests over CDP and JVM tests over JDWP on `5005` |
| `--debugger=cdp` or `dap` | JavaScript tests only |
| `--debugger=PORT` | JVM tests only |

A path narrows JavaScript tests to one file; narrow JVM tests by package name. While a debugger is attached,
JavaScript test files run one at a time.

## Measure coverage

```bash
elide run --coverage app.js
```

Elide prints a Coverage Report after the program exits, with statements, lines and functions covered per file.
JavaScript and TypeScript coverage is also written as LCOV to `.dev/reports/coverage/js/run/lcov.info` in the project,
or in the working directory outside one.

## Profile CPU time

```bash
elide run --profiler=cputracing app.js
```

```text
╭Profiler Report───────────────────────────────────────────────────────────────╮
│ Location           Root               Total        Interpreted      Compiled │
│   app.js            fib       21.89k 100.0%      21.89k 100.0%        0 0.0% │
│   app.js       :program              1 0.0%           1 100.0%        0 0.0% │
╰──────────────────────────────────────────────────────────────────────────────╯
```

`Total` counts calls to each function. For JFR recordings, heap dumps and Linux `perf`, see
[Monitoring and Profiling](https://elide.help/docs/instruments).

## Trace with Insights

```javascript
// insight.js
insight.on("enter", (ctx) => {
  console.log("enter", ctx.name);
}, { roots: true });
```

```bash
elide run --insights=insight.js app.js
```

Each function entry prints a line such as `enter fib`. See the [Insights API](https://elide.help/docs/api-insight) for events and filters.

## Report a bug

```bash
elide info
elide agent diagnostics
elide agent bug
```

`elide agent bug` prints the issue tracker URL and a Markdown report template. Fill in the exact command, the expected
behavior, and any crash report.