github-starred/actual
2
0
Fork 0
mirror of https://github.com/actualbudget/actual.git synced 2026-05-06 07:01:45 -05:00
Code Issues 1.5k Packages Projects Releases 54 Wiki Activity

[Bug]: Native Install Dependency Issues #1500

New Issue
Closed
opened 2026-02-28 19:45:30 -06:00 by GiteaMirror · 2 comments
GiteaMirror commented 2026-02-28 19:45:30 -06:00
Owner
Copy Link

Originally created by @weswitt on GitHub (Oct 11, 2024).

Verified issue does not already exist?

  • I have searched and found no existing issue
  • I will be providing steps how to reproduce the bug (in most cases this will also mean uploading a demo budget file)

What happened?

I'm running AB in docker but thought I'd try to get a native install up and running. I'm seeing the following:

yarn start
Checking if there are any migrations to run for direction "up"...
Rejection: Error: The module '/root/actual-server/node_modules/better-sqlite3/build/Release/better_sqlite3.node'
was compiled against a different Node.js version using
NODE_MODULE_VERSION 108. This version of Node.js requires
NODE_MODULE_VERSION 109. Please try re-compiling or re-installing
the module (for instance, using npm rebuild or npm install).
at Module._extensions..node (node:internal/modules/cjs/loader:1452:18)
at Module.load (node:internal/modules/cjs/loader:1197:32)
at Module._load (node:internal/modules/cjs/loader:1013:12)
at Module.require (node:internal/modules/cjs/loader:1225:19)
at require (node:internal/modules/helpers:177:18)
at bindings (/root/actual-server/node_modules/bindings/bindings.js:112:48)
at new Database (/root/actual-server/node_modules/better-sqlite3/lib/database.js:48:64)
at openDatabase (file:///root/actual-server/src/db.js:57:30)
at getAccountDb (file:///root/actual-server/src/account-db.js:12:18)
at Migration.up (file:///root/actual-server/migrations/1694360479680-create-account-db.js:4:9) {
code: 'ERR_DLOPEN_FAILED'
}

node -v
v18.19.1

npm -v
9.2.0

OS: Ubuntu 22.04

I followed the instructions at https://actualbudget.org/docs/install/local

How can I resolve the better_sqlite3 version problem?

Where are you hosting Actual?

Locally via Yarn

What browsers are you seeing the problem on?

Chrome

Operating System

Linux

Originally created by @weswitt on GitHub (Oct 11, 2024). ### Verified issue does not already exist? - [X] I have searched and found no existing issue - [X] I will be providing steps how to reproduce the bug (in most cases this will also mean uploading a demo budget file) ### What happened? I'm running AB in docker but thought I'd try to get a native install up and running. I'm seeing the following: yarn start Checking if there are any migrations to run for direction "up"... Rejection: Error: The module '/root/actual-server/node_modules/better-sqlite3/build/Release/better_sqlite3.node' was compiled against a different Node.js version using NODE_MODULE_VERSION 108. This version of Node.js requires NODE_MODULE_VERSION 109. Please try re-compiling or re-installing the module (for instance, using `npm rebuild` or `npm install`). at Module._extensions..node (node:internal/modules/cjs/loader:1452:18) at Module.load (node:internal/modules/cjs/loader:1197:32) at Module._load (node:internal/modules/cjs/loader:1013:12) at Module.require (node:internal/modules/cjs/loader:1225:19) at require (node:internal/modules/helpers:177:18) at bindings (/root/actual-server/node_modules/bindings/bindings.js:112:48) at new Database (/root/actual-server/node_modules/better-sqlite3/lib/database.js:48:64) at openDatabase (file:///root/actual-server/src/db.js:57:30) at getAccountDb (file:///root/actual-server/src/account-db.js:12:18) at Migration.up (file:///root/actual-server/migrations/1694360479680-create-account-db.js:4:9) { code: 'ERR_DLOPEN_FAILED' } node -v v18.19.1 npm -v 9.2.0 OS: Ubuntu 22.04 I followed the instructions at https://actualbudget.org/docs/install/local How can I resolve the better_sqlite3 version problem? ### Where are you hosting Actual? Locally via Yarn ### What browsers are you seeing the problem on? Chrome ### Operating System Linux
GiteaMirror added the bug label 2026-02-28 19:45:30 -06:00
GiteaMirror commented 2026-02-28 19:45:31 -06:00
Author
Owner
Copy Link

@youngcw commented on GitHub (Oct 18, 2024):

Im not sure what would cause this. Maybe reach out on discord for tech support there.

@youngcw commented on GitHub (Oct 18, 2024): Im not sure what would cause this. Maybe reach out on discord for tech support there.
GiteaMirror commented 2026-02-28 19:45:31 -06:00
Author
Owner
Copy Link

@S3NTYN3L commented on GitHub (May 3, 2025):

Fixing better-sqlite3 Node.js Version Mismatch for Actual Budget on Linux

Hi @weswitt, I saw your issue with the better-sqlite3 Node.js mismatch error (Error: The module '.../better_sqlite3.node' was compiled against a different Node.js version) and hit the same problem setting up Actual Budget on my mother’s Linux Mint 22.1 laptop.

This guide, based on the official instructions (https://actualbudget.org/docs/install/build-from-source), fixes it with a simple rebuild and includes a systemd service and update script for easy maintenance.
I’ve attached a .zip with all files—tested on Mint, but should work on any Linux distro.

Prerequisites

Install nvm, git, and yarn as needed:

  • nvm: Install Node.js version manager (https://github.com/nvm-sh/nvm#installing-and-updating): 
    curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
    Load nvm in the current session: \. "$HOME/.nvm/nvm.sh". Alternatively, reload the shell (source ~/.bashrc) or restart the terminal.
  • Node.js v18 or greater: Actual Budget requires Node.js v18 or later per the official guide. This guide uses v22 (tested on Linux Mint 22.1), but v18, v19, v20, or v21 should work with the same better-sqlite3 fix: 
    nvm install 22
  • git and yarn: Install via your package manager (e.g., on Mint/Ubuntu): 
    sudo apt update
sudo apt install git yarn

Build Steps

Follow the guide’s steps, with a fix for better-sqlite3:

  1. Clone the repo: 
    git clone https://github.com/actualbudget/actual.git ~/actual-server
    Note: I renamed the actual directory to actual-server for clarity (mv actual actual-server). Adjust paths if you keep actual.
  2. Navigate to the directory: 
    cd ~/actual-server
  3. Install dependencies: 
    yarn install
  4. Fix better-sqlite3: Rebuild native modules for your Node.js version (this guide uses v22, but v18, v19, v20, or v21 should work): 
    nvm use 22
npm rebuild
  5. Build the app: 
    yarn build:server
  6. Start the server: 
    yarn start:server
  7. Verify the UI at http://localhost:5006.

Systemd Service

To run the server automatically, use the actual-server.service file from the attached actual-budget-files.zip or create it manually:

  • Using the zipped file:

    1. Download actual-budget-files.zip (attached below).
    2. Unzip it: 
      unzip actual-budget-files.zip
    3. Move actual-server.service to the system directory: 
      sudo mv actual-server.service /etc/systemd/system/
    4. If using an older distro, edit the file to replace %h with your home directory (e.g., /home/john) and %u with your username (e.g., john): 
      sudo nano /etc/systemd/system/actual-server.service

  • Creating manually:

    sudo nano /etc/systemd/system/actual-server.service

    Paste:

    [Unit]
Description=Actual Budget Server (https://actualbudget.org/)
After=network.target

[Service]
WorkingDirectory=%h/actual-server
ExecStart=/bin/bash -c 'source %h/.nvm/nvm.sh && nvm use 22 && yarn start:server'
Restart=always
User=%u
Environment=NODE_ENV=production
Environment=PORT=5006

[Install]
WantedBy=multi-user.target

Note: %h and %u are systemd specifiers for the user’s home directory and username.
If they don’t work (e.g., older distros), replace with your home path and username (e.g., /home/john and john).

Enable and start the service:

sudo systemctl daemon-reload
sudo systemctl enable actual-server.service
sudo systemctl start actual-server.service

Verify it’s running:

sudo systemctl status actual-server.service
curl http://localhost:5006

Update Script

To handle updates when Actual Budget prompts, use the update-actual-server.sh file from the attached actual-budget-files.zip or create it manually:

  • Using the zipped file:

    1. Download actual-budget-files.zip (attached below).
    2. Unzip it: 
      unzip actual-budget-files.zip
    3. Place update-actual-server.sh in ~/actual-server: 
      mv update-actual-server.sh ~/actual-server/
    4. Make it executable: 
      chmod +x ~/actual-server/update-actual-server.sh

  • Creating manually:

    nano ~/actual-server/update-actual-server.sh

    Paste:

    #!/bin/bash

# Script to update Actual Budget server
# Run this when the web UI prompts for an update

# Exit on any error
set -e

echo "Starting Actual Budget server update..."
echo ""

# Ensure nvm is available
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

# Use Node.js v22
echo "Setting Node.js version to 22..."
nvm use 22 || { echo "Failed to set Node.js v22. Ensure nvm is installed and v22 is available."; exit 1; }
echo ""

# Navigate to actual-server directory
echo "Navigating to actual-server directory..."
cd "$HOME/actual-server" || { echo "Directory $HOME/actual-server not found."; exit 1; }
echo ""

# Pull latest code
echo "Pulling latest code from Git..."
git pull origin master || { echo "Failed to pull latest code. Check git configuration."; exit 1; }
echo ""

# Update dependencies
echo "Updating dependencies..."
yarn install || { echo "Failed to update dependencies with yarn."; exit 1; }
echo ""

# Rebuild native modules for Node.js v22
echo "Rebuilding native modules..."
npm rebuild || { echo "Failed to rebuild native modules."; exit 1; }
echo ""

# Build the server and frontend
echo "Building server and frontend..."
yarn build:server || { echo "Failed to build server and frontend. Check if 'build:server' is in package.json."; exit 1; }
echo ""

# Stop the server
echo "Stopping actual-server service..."
sudo systemctl stop actual-server.service || { echo "Failed to stop actual-server service."; exit 1; }
echo ""

# Start the server
echo "Starting actual-server service..."
sudo systemctl start actual-server.service || { echo "Failed to start actual-server service."; exit 1; }
echo ""

# Wait a moment for the server to start
sleep 5

# Check service status
echo "Checking service status..."
if systemctl is-active --quiet actual-server.service; then
    echo "Actual-server service is running!"
else
    echo "Error: actual-server service failed to start."
    echo "Showing recent logs (last 50 lines from today, newest first):"
    sudo journalctl -u actual-server.service --since=today -r -n 50 --no-pager
    exit 1
fi
echo ""

# Check if the UI is accessible
echo "Checking if the web UI is accessible..."
if curl -s http://localhost:5006 > /dev/null; then
    echo "Success! Actual Budget is updated and accessible at http://localhost:5006."
else
    echo "Error: Web UI is not accessible."
    echo "Showing recent logs (last 50 lines from today, newest first):"
    sudo journalctl -u actual-server.service --since=today -r -n 50 --no-pager
    exit 1
fi
echo ""

echo "Update complete! You can now use the updated Actual Budget app."

Make it executable:

chmod +x ~/actual-server/update-actual-server.sh

Test it:

~/actual-server/update-actual-server.sh

Desktop File

For easy updates, use the Update-Actual-Budget.desktop file from the attached actual-budget-files.zip or create it manually:

  • Using the zipped file:

    1. Download actual-budget-files.zip (attached below).
    2. Unzip it: 
      unzip actual-budget-files.zip
    3. Place Update-Actual-Budget.desktop on the desktop: 
      mv Update-Actual-Budget.desktop ~/Desktop/
    4. Make it executable: 
      chmod +x ~/Desktop/Update-Actual-Budget.desktop

  • Creating manually:

    nano ~/Desktop/Update-Actual-Budget.desktop

    Paste:

    [Desktop Entry]
Name=Update Actual Budget
Exec=gnome-terminal -- /bin/bash -c "$HOME/actual-server/update-actual-server.sh; echo 'Press Enter to close...'; read"
Type=Application
Terminal=true
Icon=system-software-update

Make it executable:

chmod +x ~/Desktop/Update-Actual-Budget.desktop

Note: gnome-terminal is Mint’s default. For other distros, check your desktop environment (echo $XDG_CURRENT_DESKTOP) and replace with xfce4-terminal, konsole, xterm, etc., as needed.

Sudoers Setup

The update script uses sudo systemctl, which requires a password unless configured. Add a sudoers rule:

sudo visudo -f /etc/sudoers.d/actual-server

Add (replace YOUR_USERNAME with the actual username):

YOUR_USERNAME ALL=(ALL) NOPASSWD: /bin/systemctl stop actual-server.service, /bin/systemctl start actual-server.service

Test it:

sudo systemctl stop actual-server.service
sudo systemctl start actual-server.service

Instructions for Updates

When Actual Budget prompts for an update:

  1. Double-click “Update Actual Budget” on the desktop.
  2. Wait for “Update complete!” and press Enter to close.
  3. Refresh http://localhost:5006.

Troubleshooting

If better-sqlite3 errors persist:

cd ~/actual-server
nvm use 22
npm rebuild
yarn build:server
sudo systemctl restart actual-server.service

If the service or UI fails:

  • Check Node.js version: node -v (should be v18 or greater).
  • Check logs: sudo journalctl -u actual-server.service --since=today -r -n 50 --no-pager.
  • Verify UI: curl http://localhost:5006.

This setup assumes a single-user system. For multi-user systems, adjust permissions or run the service as a specific user.

Note to Devs

Feel free to use, adapt, or incorporate this guide into the Actual Budget documentation or troubleshooting resources.
I hope it helps other users avoid the better-sqlite3 issue!

actual-budget-files.zip

@S3NTYN3L commented on GitHub (May 3, 2025): # Fixing `better-sqlite3` Node.js Version Mismatch for Actual Budget on Linux Hi @weswitt, I saw your issue with the `better-sqlite3` Node.js mismatch error (`Error: The module '.../better_sqlite3.node' was compiled against a different Node.js version`) and hit the same problem setting up Actual Budget on my mother’s Linux Mint 22.1 laptop. This guide, based on the official instructions (https://actualbudget.org/docs/install/build-from-source), fixes it with a simple rebuild and includes a `systemd` service and update script for easy maintenance. I’ve attached a `.zip` with all files—tested on Mint, but should work on any Linux distro. ## Prerequisites Install `nvm`, `git`, and `yarn` as needed: - **nvm**: Install Node.js version manager (https://github.com/nvm-sh/nvm#installing-and-updating): ```bash curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash ``` Load `nvm` in the current session: `\. "$HOME/.nvm/nvm.sh"`. Alternatively, reload the shell (`source ~/.bashrc`) or restart the terminal. - **Node.js v18 or greater**: Actual Budget requires Node.js v18 or later per the official guide. This guide uses v22 (tested on Linux Mint 22.1), but v18, v19, v20, or v21 should work with the same `better-sqlite3` fix: ```bash nvm install 22 ``` - **git** and **yarn**: Install via your package manager (e.g., on Mint/Ubuntu): ```bash sudo apt update sudo apt install git yarn ``` ## Build Steps Follow the guide’s steps, with a fix for `better-sqlite3`: 1. Clone the repo: ```bash git clone https://github.com/actualbudget/actual.git ~/actual-server ``` Note: I renamed the `actual` directory to `actual-server` for clarity (`mv actual actual-server`). Adjust paths if you keep `actual`. 2. Navigate to the directory: ```bash cd ~/actual-server ``` 3. Install dependencies: ```bash yarn install ``` 4. **Fix `better-sqlite3`**: Rebuild native modules for your Node.js version (this guide uses v22, but v18, v19, v20, or v21 should work): ```bash nvm use 22 npm rebuild ``` 5. Build the app: ```bash yarn build:server ``` 6. Start the server: ```bash yarn start:server ``` 7. Verify the UI at `http://localhost:5006`. ## Systemd Service To run the server automatically, use the `actual-server.service` file from the attached `actual-budget-files.zip` or create it manually: - **Using the zipped file**: 1. Download `actual-budget-files.zip` (attached below). 2. Unzip it: ```bash unzip actual-budget-files.zip ``` 3. Move `actual-server.service` to the system directory: ```bash sudo mv actual-server.service /etc/systemd/system/ ``` 4. If using an older distro, edit the file to replace `%h` with your home directory (e.g., `/home/john`) and `%u` with your username (e.g., `john`): ```bash sudo nano /etc/systemd/system/actual-server.service ``` - **Creating manually**: ```bash sudo nano /etc/systemd/system/actual-server.service ``` Paste: ```bash [Unit] Description=Actual Budget Server (https://actualbudget.org/) After=network.target [Service] WorkingDirectory=%h/actual-server ExecStart=/bin/bash -c 'source %h/.nvm/nvm.sh && nvm use 22 && yarn start:server' Restart=always User=%u Environment=NODE_ENV=production Environment=PORT=5006 [Install] WantedBy=multi-user.target ``` Note: `%h` and `%u` are systemd specifiers for the user’s home directory and username. If they don’t work (e.g., older distros), replace with your home path and username (e.g., `/home/john` and `john`). Enable and start the service: ```bash sudo systemctl daemon-reload sudo systemctl enable actual-server.service sudo systemctl start actual-server.service ``` Verify it’s running: ```bash sudo systemctl status actual-server.service curl http://localhost:5006 ``` ## Update Script To handle updates when Actual Budget prompts, use the `update-actual-server.sh` file from the attached `actual-budget-files.zip` or create it manually: - **Using the zipped file**: 1. Download `actual-budget-files.zip` (attached below). 2. Unzip it: ```bash unzip actual-budget-files.zip ``` 3. Place `update-actual-server.sh` in `~/actual-server`: ```bash mv update-actual-server.sh ~/actual-server/ ``` 4. Make it executable: ```bash chmod +x ~/actual-server/update-actual-server.sh ``` - **Creating manually**: ```bash nano ~/actual-server/update-actual-server.sh ``` Paste: ```bash #!/bin/bash # Script to update Actual Budget server # Run this when the web UI prompts for an update # Exit on any error set -e echo "Starting Actual Budget server update..." echo "" # Ensure nvm is available export NVM_DIR="$HOME/.nvm" [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" # Use Node.js v22 echo "Setting Node.js version to 22..." nvm use 22 || { echo "Failed to set Node.js v22. Ensure nvm is installed and v22 is available."; exit 1; } echo "" # Navigate to actual-server directory echo "Navigating to actual-server directory..." cd "$HOME/actual-server" || { echo "Directory $HOME/actual-server not found."; exit 1; } echo "" # Pull latest code echo "Pulling latest code from Git..." git pull origin master || { echo "Failed to pull latest code. Check git configuration."; exit 1; } echo "" # Update dependencies echo "Updating dependencies..." yarn install || { echo "Failed to update dependencies with yarn."; exit 1; } echo "" # Rebuild native modules for Node.js v22 echo "Rebuilding native modules..." npm rebuild || { echo "Failed to rebuild native modules."; exit 1; } echo "" # Build the server and frontend echo "Building server and frontend..." yarn build:server || { echo "Failed to build server and frontend. Check if 'build:server' is in package.json."; exit 1; } echo "" # Stop the server echo "Stopping actual-server service..." sudo systemctl stop actual-server.service || { echo "Failed to stop actual-server service."; exit 1; } echo "" # Start the server echo "Starting actual-server service..." sudo systemctl start actual-server.service || { echo "Failed to start actual-server service."; exit 1; } echo "" # Wait a moment for the server to start sleep 5 # Check service status echo "Checking service status..." if systemctl is-active --quiet actual-server.service; then echo "Actual-server service is running!" else echo "Error: actual-server service failed to start." echo "Showing recent logs (last 50 lines from today, newest first):" sudo journalctl -u actual-server.service --since=today -r -n 50 --no-pager exit 1 fi echo "" # Check if the UI is accessible echo "Checking if the web UI is accessible..." if curl -s http://localhost:5006 > /dev/null; then echo "Success! Actual Budget is updated and accessible at http://localhost:5006." else echo "Error: Web UI is not accessible." echo "Showing recent logs (last 50 lines from today, newest first):" sudo journalctl -u actual-server.service --since=today -r -n 50 --no-pager exit 1 fi echo "" echo "Update complete! You can now use the updated Actual Budget app." ``` Make it executable: ```bash chmod +x ~/actual-server/update-actual-server.sh ``` Test it: ```bash ~/actual-server/update-actual-server.sh ``` ## Desktop File For easy updates, use the `Update-Actual-Budget.desktop` file from the attached `actual-budget-files.zip` or create it manually: - **Using the zipped file**: 1. Download `actual-budget-files.zip` (attached below). 2. Unzip it: ```bash unzip actual-budget-files.zip ``` 3. Place `Update-Actual-Budget.desktop` on the desktop: ```bash mv Update-Actual-Budget.desktop ~/Desktop/ ``` 4. Make it executable: ```bash chmod +x ~/Desktop/Update-Actual-Budget.desktop ``` - **Creating manually**: ```bash nano ~/Desktop/Update-Actual-Budget.desktop ``` Paste: ```bash [Desktop Entry] Name=Update Actual Budget Exec=gnome-terminal -- /bin/bash -c "$HOME/actual-server/update-actual-server.sh; echo 'Press Enter to close...'; read" Type=Application Terminal=true Icon=system-software-update ``` Make it executable: ```bash chmod +x ~/Desktop/Update-Actual-Budget.desktop ``` Note: `gnome-terminal` is Mint’s default. For other distros, check your desktop environment (`echo $XDG_CURRENT_DESKTOP`) and replace with `xfce4-terminal`, `konsole`, `xterm`, etc., as needed. ## Sudoers Setup The update script uses `sudo systemctl`, which requires a password unless configured. Add a `sudoers` rule: ```bash sudo visudo -f /etc/sudoers.d/actual-server ``` Add (replace `YOUR_USERNAME` with the actual username): ```bash YOUR_USERNAME ALL=(ALL) NOPASSWD: /bin/systemctl stop actual-server.service, /bin/systemctl start actual-server.service ``` Test it: ```bash sudo systemctl stop actual-server.service sudo systemctl start actual-server.service ``` ## Instructions for Updates When Actual Budget prompts for an update: 1. Double-click “Update Actual Budget” on the desktop. 2. Wait for “Update complete!” and press Enter to close. 3. Refresh `http://localhost:5006`. ## Troubleshooting If `better-sqlite3` errors persist: ```bash cd ~/actual-server nvm use 22 npm rebuild yarn build:server sudo systemctl restart actual-server.service ``` If the service or UI fails: - Check Node.js version: `node -v` (should be v18 or greater). - Check logs: `sudo journalctl -u actual-server.service --since=today -r -n 50 --no-pager`. - Verify UI: `curl http://localhost:5006`. This setup assumes a single-user system. For multi-user systems, adjust permissions or run the service as a specific user. ## Note to Devs Feel free to use, adapt, or incorporate this guide into the Actual Budget documentation or troubleshooting resources. I hope it helps other users avoid the `better-sqlite3` issue! [actual-budget-files.zip](https://github.com/user-attachments/files/20020562/actual-budget-files.zip)
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
AI generated
API
bank sync
budgeting
bug
can’t replicate
dependencies
docker
documentation
electron
experimental feature
feature
feedback
goal templates
good first issue
help wanted
importers
maintenance
needs info
needs testing
needs triage
needs votes
openid
payees
pull-request
Mirrored from GitHub Pull Request
 regression
reports
responsive
rules
schedules
server
✨ merged
split transactions
tech debt
theme
transaction import
transaction reconciliation
transactions
translations
upstream
user interface
✅ approved
wontfix
No Label bug
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
GiteaMirror ninjasurge
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: github-starred/actual#1500
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?