# Troubleshooting

> Common Elide errors with their exact messages and fixes: missing modules, Python, JVM tools, sandbox denials, timeouts, memory and ports.

Each section quotes an error as Elide prints it, then the fix.

## No such built-in module

```text
Error: No such built-in module: node:http2
```

`node:http2`, `node:cluster`, `node:inspector` and `node:wasi` are not available; `require` gives the code
`ERR_UNKNOWN_BUILTIN_MODULE`. Without the `node:` prefix the message is `Cannot find module 'http2'`. A package that
imports one at load time, such as Fastify, fails the same way. Check a module's status in the
[API Overview](https://elide.help/docs/api-overview).

## Module not found after `elide install`

```text
TypeError: Module not found: 'hono'
```

Plain `elide install` installs Maven dependencies only. With only a `package.json`, it prints nothing and exits `0`.
Install npm packages with:

```bash
elide install --ecosystems=npm
```

## Python is not installed

```text
Python support is not installed. Run 'elide setup python' to add it.
```

Exit code `2`. Run `elide setup python`; `elide info` lists the installed languages on its `Languages:` line. A JavaScript
file that imports a `.py` module before Python is installed exits `1` with
`Cannot import 'mod.py': Python support is not installed.` and the same hint. With Python installed, calls between
languages also need `--interop`; see [Languages and Interop](https://elide.help/docs/languages#without---interop).

## `elide javac` without `--`

```text
error: '[-- TOOL_ARGS]…' can only be given after '--'

Usage: elide javac [FLAGS] [-- TOOL_ARGS]…
```

Arguments for `javac`, `java`, `kotlinc` and the other JDK tools go after `--`:

```bash
elide javac -- -d out Hello.java
elide java -- -cp out Hello
```

## Kotlin classes fail under `elide java`

```bash
elide kotlinc -- -d kout Main.kt
elide java -- -cp kout MainKt
```

```text
Exception in thread "main" java.lang.NoClassDefFoundError: kotlin/collections/CollectionsKt
	at MainKt.main(Main.kt:2)
	at MainKt.main(Main.kt)
Caused by: java.lang.ClassNotFoundException: kotlin.collections.CollectionsKt
```

`elide java` does not add the Kotlin standard library. Run the file with `elide run Main.kt`, or package the app as a
[`Jvm.JvmApplication`](https://elide.help/docs/toolchain/jvm/jar#runnable-application-distributions). `kotlinc -include-runtime` fails.

## Sandbox denials

| Message | Grant |
| --- | --- |
| `EACCES: permission denied, open 'hello.txt'` | `--allow-read=PATHS` or `--allow-write=PATHS` |
| `Error: Filesystem read denied by policy: /app/node_modules/hono` | Add the npm store to `--allow-read`; packages link into `~/.cache/aube` |
| `fetch to 'example.com:443' is not permitted; grant it with --allow-net=example.com` | The flag in the message |
| `spawn of 'echo' is not permitted; grant it with --allow-run=echo` | The flag in the message |
| `fetch to 'example.com:443' denied by --deny-net` | Remove the host from `--deny-net` |
| `spawn of 'echo' denied by --deny-run` | Remove the command from `--deny-run` |

See [Sandbox and Limits](https://elide.help/docs/sandbox).

## `--deny-net` without `=`

```text
error: equal sign is needed when assigning values to '--deny-net=<HOSTS>'
```

Exit code `2`. Write `--deny-net=example.com`; the same holds for `--deny-run`. The `--allow-*` flags take an optional
value, so `--allow-net example.com run app.js` grants every host and tries to run a file named `example.com`:

```text
No file or script named 'example.com'
```

## Exit code 124

```text
Error: --timeout 2s exceeded
```

`--timeout=DURATION` stopped the run. Raise it or remove it.

## Exit code 3 and out of memory

`--heap-dump-on-oom=FILE` writes a heap dump when the heap is full, then exits `3`:

```text
Dumping heap to …/oom.hprof ...
Heap dump file created [308989015 bytes in 0.988 secs]
```

Without it, a full heap exits `1` with
`Could not allocate an unaligned heap chunk because the heap address space is exhausted.` Raise `--max-mem`. A value of
`128m` or less fails before the program starts:

```text
Failed to create isolate: INSUFFICIENT_ADDRESS_SPACE (802)
```

## Port already in use

`node:http` reports a taken port:

```text
Error: listen EADDRINUSE 127.0.0.1:3000
```

Fetch-handler servers (`export default { fetch }`, `Elide.serve`) report nothing: a second server on the same port
starts, and requests alternate between the two processes. Stop the old one first:

```bash
ss -ltnp | grep :3000
```

## A request returns 500 with no error printed

```text
HTTP/1.1 500 Internal Server Error
```

A fetch handler that throws answers `500 Internal Server Error` without printing the error. Wrap the handler in
`try`/`catch` and log it. See [Build an HTTP Service](https://elide.help/docs/http-service#errors).

## Express `express.json()` stops the server

```text
TypeError: Buffer.isBuffer is not a function
```

`express.json()` and `express.text()` stop the process on the first request with a body. Read the body yourself or use
`express.raw()`; see [Frameworks](https://elide.help/docs/http-service#frameworks).