ERPNext/Frappe v15 to v16 upgrade on Debian 12 — Python 3.14 + Node 24 + Supervisor fix
This is what finally worked for me after getting stuck in bench switch-to-branch version-16 ... --upgrade errors and Supervisor socketio spawn errors.
-
Frappe v16 requires Python 3.14 (or you will get SyntaxError on
type X = ...) -
Frappe v16 should run on Node 24
-
Bench uses the internal venv
~/frappe-bench/env, not whatever venv you manually activate -
Socketio may fail with
ECONNREFUSED 127.0.0.1:11000unless bench redis processes are running
Make sure you take a snapshot or backup your installation before you start!
1. Install Node 24 (and make sure supervisor can find it)
If you use nvm:
su - <username>
source ~/.bashrc 2>/dev/null || true
nvm install 24
nvm use 24
nvm alias default 24
But supervisor often does NOT load nvm paths, so install Node 24 system-wide too:
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt-get install -y nodejs
2. Install Python 3.14.2 using pyenv
Install build dependencies:
sudo apt update
sudo apt install -y \
build-essential libssl-dev zlib1g-dev libbz2-dev libreadline-dev libsqlite3-dev \
libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev \
curl git
Install pyenv:
curl https://pyenv.run | bash
Edit ~/.bashrc:
nano ~/.bashrc
Add these lines at the bottom:
export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"
eval "$(pyenv virtualenv-init -)"
Reload shell:
exec $SHELL
Install + enable Python 3.14.2:
pyenv install 3.14.2
pyenv global 3.14.2
python --version
3. Rebuild bench internal env with Python 3.14
Stop services (important during upgrade)
sudo supervisorctl stop all || true
sudo systemctl stop nginx || true
Bench uses: ~/frappe-bench/env/bin/python
cd ~/frappe-bench
rm -rf ~/frappe-bench/env
python -m venv ~/frappe-bench/env
source ~/frappe-bench/env/bin/activate
python --version # MUST show 3.14.x
pip install -U pip wheel setuptools
pip install -U frappe-bench
Reinstall core apps (editable):
pip install -e apps/frappe # ignore dependency warnings if any
pip install -e apps/erpnext # ignore dependency warnings if any
pip install -e apps/hrms # ignore dependency warnings if any
4. Switch apps to version-16
cd ~/frappe-bench
source ~/frappe-bench/env/bin/activate
bench switch-to-branch version-16 frappe --upgrade
bench switch-to-branch version-16 erpnext --upgrade
bench switch-to-branch version-16 hrms --upgrade
Then patch update:
bench update --patch
5. Fix Supervisor socketio spawn error (redis_cache not running)
If you get errors like:
-
Service redis_cache is not running -
socketio spawn error -
ECONNREFUSED 127.0.0.1 port 11000
Start bench redis + workers FIRST:
sudo supervisorctl start frappe-bench-redis:
sudo supervisorctl start frappe-bench-workers:
Then restart socketio:
sudo supervisorctl restart frappe-bench-web:frappe-bench-node-socketio
Verify everything is running:
sudo supervisorctl status | egrep 'redis|socketio|frappe-web|worker'
Also make sure system redis is enabled (doesn’t hurt):
sudo systemctl enable --now redis-server
sudo systemctl restart redis-server
6. Final update + build + migrate
cd ~/frappe-bench
source ~/frappe-bench/env/bin/activate
bench update --requirements
bench build
bench --site <site> migrate
Restart services:
sudo supervisorctl restart all
sudo systemctl restart nginx
