Debugging

Find and report problems in programs run with Elide.

Read errors

Terminal

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.

Viewing an uncaught program error in Elide

 ~/demo  elide ./checkout.js
╭Script Error────────────────────────────────────────────────────────────────╮
│ RangeError: discount must be a fraction, got 25                            │
│                                                                            │
│  In file checkout.js:3:11:                                                 │
│     ╭─                                                                     │
│   2 │   if (pct > 1) {                                                     │
│ → 3 │     throw new RangeError(`discount must be a fraction, got ${pct}`); │
│   4 │   }                                                                  │
│   5 │   return order.total * (1 - pct);                                    │
│   6 │ }                                                                    │
│   · │                                                                      │
│ Stack Trace────────────────────────────────                                │
│  ╭─ [js] applyDiscount checkout.js:3:11-67                                 │
│  │                                                                         │
│  · elide ./checkout.js                                                     │
│ Advice──────────────────────────────────────────────────────────────────── │
│  An error occurred while executing your code.                              │
╰────────────────────────────────────────────────────────────────────────────╯

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.

elide --profiler and --debugger — profiler report and debug endpoints

 ~/demo  elide --profiler=cputracing pricing.js
total: 48
╭Profiler Report───────────────────────────────────────────────────────────────────────────────────╮
│   Location                 Root               Total             Interpreted             Compiled │
│ pricing.js                price             1 50.0%                1 100.0%               0 0.0% │
│ pricing.js             :program             1 50.0%                1 100.0%               0 0.0% │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
 ~/demo  elide --debugger=dap pricing.js
[Graal DAP] Starting server and listening on /127.0.0.1:4711

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`

Terminal

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

utf-8 · text · Lines: 3

Open the devtools:// link in Chrome.

Terminal

bash

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

text

Listening for transport dt_socket at address: 5005

utf-8 · text · Lines: 1

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

Terminal

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

Terminal

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

Terminal

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

Terminal

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% │
╰──────────────────────────────────────────────────────────────────────────────╯

utf-8 · text · Lines: 5

Total counts calls to each function. For JFR recordings, heap dumps and Linux perf, see Monitoring and Profiling.

Trace with Insights

javascript

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

utf-8 · javascript · Lines: 4

Terminal

bash

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

Each function entry prints a line such as enter fib. See the Insights API for events and filters.

Report a bug

Terminal

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.