From e75baed4b65c32b952cf1432cd632198e8b93754 Mon Sep 17 00:00:00 2001 From: jonesfernandess Date: Sat, 11 Apr 2026 09:44:45 -0300 Subject: [PATCH] docs: add macOS better-sqlite3 rebuild fix to troubleshooting (#1119) Integrated into release/v3.6.2 --- docs/TROUBLESHOOTING.md | 27 ++++++++++++++++++++ docs/i18n/pt-BR/docs/TROUBLESHOOTING.md | 33 ++++++++++++++++++++++--- 2 files changed, 57 insertions(+), 3 deletions(-) diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md index e9d67d43a7..aa28a08fcf 100644 --- a/docs/TROUBLESHOOTING.md +++ b/docs/TROUBLESHOOTING.md @@ -16,6 +16,7 @@ Common problems and solutions for OmniRoute. | 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 | +| `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 | --- @@ -47,6 +48,32 @@ Common problems and solutions for OmniRoute. > **Supported versions:** Node.js 18, 20, or 22 LTS. Node.js 24+ is **not supported**. +### macOS: `dlopen` / "slice is not valid mach-o file" + + + +**Cause:** After a global `npm install -g omniroute`, the `better-sqlite3` native binary inside the package may have been compiled for a different architecture or Node.js ABI than what is running locally. This is common on macOS (both Apple Silicon and Intel) when the pre-built binary does not match your environment. + +**Symptoms:** + +- Server fails immediately on startup with a `dlopen` error +- Error contains `slice is not valid mach-o file` +- Full example: + +``` +dlopen(/Users//.nvm/versions/node/v24.13.1/lib/node_modules/omniroute/app/node_modules/better-sqlite3/build/Release/better_sqlite3.node, 0x0001): tried: '...' (slice is not valid mach-o file) +``` + +**Fix — rebuild for your local environment (no Node.js downgrade required):** + +```bash +cd $(npm root -g)/omniroute/app +npm rebuild better-sqlite3 +omniroute +``` + +> **Note:** This recompiles the native binding against your local Node.js version and CPU architecture, resolving the binary mismatch. The officially supported range remains **Node.js 18, 20, or 22 LTS** (`engines` field in `package.json`). If you are on Node.js 24, the rebuild may silence this specific startup error but other issues can still occur — downgrading to Node.js 22 LTS remains the recommended path. + --- ## Proxy Issues diff --git a/docs/i18n/pt-BR/docs/TROUBLESHOOTING.md b/docs/i18n/pt-BR/docs/TROUBLESHOOTING.md index e602c4cc4d..c68816bbd2 100644 --- a/docs/i18n/pt-BR/docs/TROUBLESHOOTING.md +++ b/docs/i18n/pt-BR/docs/TROUBLESHOOTING.md @@ -17,8 +17,9 @@ 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 | -| Proxy "fetch failed" | Ensure proxy config is set at the correct level — see [Proxy Issues](#proxy-issues) below | +| Login crash / tela em branco | Pode ser Node.js 24+ — veja [Compatibilidade com Node.js](#nodejs-compatibility) abaixo | +| `dlopen` / `slice is not valid mach-o file` (macOS) | Execute `cd $(npm root -g)/omniroute/app && npm rebuild better-sqlite3 && omniroute` — veja [Rebuild nativo no macOS](#macos-native-module-rebuild) abaixo | +| Proxy "fetch failed" | Verifique se o proxy está configurado no nível correto — veja [Problemas de Proxy](#proxy-issues) abaixo | --- @@ -47,7 +48,33 @@ Common problems and solutions for OmniRoute. 3. Reinstall OmniRoute: `npm install -g omniroute` 4. Restart: `omniroute` -> **Supported versions:** Node.js 18, 20, or 22 LTS. Node.js 24+ is **not supported**. +> **Versões suportadas:** Node.js 18, 20 ou 22 LTS. Node.js 24+ **não é suportado**. + +### macOS: `dlopen` / "slice is not valid mach-o file" + + + +**Causa:** Após `npm install -g omniroute`, o binário nativo do `better-sqlite3` incluído no pacote pode ter sido compilado para uma arquitetura ou versão ABI do Node.js diferente da que está sendo usada localmente. Isso é comum no macOS (Apple Silicon e Intel) quando o binário pré-compilado não corresponde ao ambiente. + +**Sintomas:** + +- O servidor falha imediatamente ao iniciar com um erro `dlopen` +- A mensagem contém `slice is not valid mach-o file` +- Exemplo completo: + +``` +dlopen(/Users//.nvm/versions/node/v24.13.1/lib/node_modules/omniroute/app/node_modules/better-sqlite3/build/Release/better_sqlite3.node, 0x0001): tried: '...' (slice is not valid mach-o file) +``` + +**Solução — recompilar para o ambiente local (sem precisar fazer downgrade do Node.js):** + +```bash +cd $(npm root -g)/omniroute/app +npm rebuild better-sqlite3 +omniroute +``` + +> **Nota:** Isso recompila o binding nativo para a versão e arquitetura local do Node.js, resolvendo o erro de incompatibilidade de binário. O intervalo oficialmente suportado continua sendo **Node.js 18, 20 ou 22 LTS** (campo `engines` no `package.json`). Se você estiver no Node.js 24, o rebuild pode silenciar este erro específico de inicialização, mas outros problemas ainda podem ocorrer — fazer downgrade para o Node.js 22 LTS continua sendo o caminho recomendado. ---