Skip to content

docs: fix outdated Node 24 warnings in TROUBLESHOOTING.md #1343

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
diegosouzapw merged 2 commits into from
Apr 16, 2026
Merged

docs: fix outdated Node 24 warnings in TROUBLESHOOTING.md #1343

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4476e05
docs: fix outdated Node 24 warnings in TROUBLESHOOTING.md
oyi77 Apr 16, 2026
9a8b7c8
docs: address Gemini review feedback
oyi77 Apr 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions Dockerfile
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
FROM node:24-trixie-slim AS builder
FROM node:24.14.1-trixie-slim AS builder
WORKDIR /app

RUN apt-get update \
Expand All @@ -13,7 +13,7 @@ RUN if [ -f package-lock.json ]; then npm ci --no-audit --no-fund; else npm inst
COPY . ./
RUN mkdir -p /app/data && npm run build -- --webpack

FROM node:24-trixie-slim AS runner-base
FROM node:24.14.1-trixie-slim AS runner-base
WORKDIR /app

LABEL org.opencontainers.image.title="omniroute" \
Expand Down
17 changes: 7 additions & 10 deletions docs/TROUBLESHOOTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ Common problems and solutions for OmniRoute.
| No logs written to disk | Set `APP_LOG_TO_FILE=true` and verify call log capture is enabled |
| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` |
| Routing strategy not saving | Update to v1.4.11+ (Zod schema fix for settings persistence) |
| Login crash / blank page | You may be on Node.js 24+ — see [Node.js Compatibility](#nodejs-compatibility) below |
| Login crash / blank page | Check Node.js version — see [Node.js Compatibility](#nodejs-compatibility) below |
| `dlopen` / `slice is not valid mach-o file` (macOS) | Run `cd $(npm root -g)/omniroute/app && npm rebuild better-sqlite3 && omniroute` — see [macOS native module rebuild](#macos-native-module-rebuild) below |
| Proxy "fetch failed" | Ensure proxy config is set at the correct level — see [Proxy Issues](#proxy-issues) below |

Expand All @@ -27,10 +27,7 @@ Common problems and solutions for OmniRoute.

### Login page crashes or shows "Module self-registration" error

**Cause:** You are running a Node.js version outside OmniRoute's approved secure runtime floor. Two cases matter:

1. **Node.js 24+**: `better-sqlite3` is not supported here and startup can fail hard.
2. **Older Node 20/22 patch levels**: the runtime may start, but it falls below the patched security floor OmniRoute now requires.
**Cause:** You are running a Node.js version outside OmniRoute's approved secure runtime floor. The most common case is running an older Node 20/22 patch level that falls below the patched security floor OmniRoute requires.

@gemini-code-assist gemini-code-assist Bot Apr 16, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The description of the "most common case" for Node.js version issues should be updated to include Node 24, as it is now a supported and recommended version. This ensures the documentation remains consistent with the changes made elsewhere in this PR.

Suggested change
**Cause:** You are running a Node.js version outside OmniRoute's approved secure runtime floor. The most common case is running an older Node 20/22 patch level that falls below the patched security floor OmniRoute requires.
**Cause:** You are running a Node.js version outside OmniRoute's approved secure runtime floor. The most common case is running an older Node 20, 22, or 24 patch level that falls below the patched security floor OmniRoute requires.


**Symptoms:**

Expand All @@ -40,16 +37,16 @@ Common problems and solutions for OmniRoute.

**Fix:**

1. Install a patched Node.js 22 LTS release (recommended):
1. Install a supported Node.js LTS release (recommended: Node.js 24.x):
```bash
nvm install 22.22.2
nvm use 22.22.2
nvm install 24
nvm use 24
```
2. Verify your version: `node --version` should show `v22.22.2` or newer on the 22.x LTS line
2. Verify your version: `node --version` should show `v24.0.0` or newer

@gemini-code-assist gemini-code-assist Bot Apr 16, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The verification step should specify that the version should be on the 24.x line. Without this clarification, "v24.0.0 or newer" could be interpreted as including Node 25+, which is explicitly excluded from the supported range (<25) and the engines field in package.json.

Suggested change
2. Verify your version: `node --version` should show `v24.0.0` or newer
2. Verify your version: node --version should show v24.0.0 or newer on the 24.x LTS line

3. Reinstall OmniRoute: `npm install -g omniroute`
4. Restart: `omniroute`

> **Supported secure versions:** `>=20.20.2 <21` or `>=22.22.2 <23`. Node.js 24+ is **not supported**.
> **Supported secure versions:** `>=20.20.2 <21`, `>=22.22.2 <23`, or `>=24.0.0 <25`. Node.js 24.x LTS (Krypton) is fully supported.

### macOS: `dlopen` / "slice is not valid mach-o file"

Expand Down
2 changes: 1 addition & 1 deletion src/shared/utils/nodeRuntimeSupport.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ export const SECURE_NODE_LINES = Object.freeze([
export const RECOMMENDED_NODE_VERSION = "24.14.1";
export const SUPPORTED_NODE_RANGE = ">=20.20.2 <21 || >=22.22.2 <23 || >=24.0.0 <25";
export const SUPPORTED_NODE_DISPLAY =
"Node.js 20.20.2+ (20.x LTS), 22.22.2+ (22.x LTS), or 24.x (24.x LTS)";
"Node.js 20.20.2+ (20.x LTS), 22.22.2+ (22.x LTS), or 24.0.0+ (24.x LTS)";

export interface NodeVersionInfo {
major: number;
Expand Down