Aurelio Finance runs from source on your own machine, which gives you privacy and control, but it also means setup hiccups land on your desk instead of a support team’s. The good news: almost every problem falls into a small set of familiar causes with straightforward fixes. This guide covers the most common ones in the order you are most likely to hit them.
First: Confirm the Prerequisites Are Actually Installed
Most failures trace back to one of the three prerequisites: Git, Node.js 22 or newer, and uv. The start script needs all three, and a partial install produces confusing errors. Before anything else, verify each one.
Open a terminal (Command Prompt or PowerShell on Windows, Terminal on macOS/Linux) and run:
git --versionshould print a version number. If the command is not found, install Git from git-scm.com.node --versionshould print v22 or higher. If it prints v20, v18, or “not recognized”, you need a newer Node.js from nodejs.org. Aurelio Finance needs Node 22+, and an older version is the single most common cause of startup failures.uv --versionshould print a version number. If it is missing, install uv from docs.astral.sh/uv.
“Port 8000 Is Already in Use”
If the app refuses to start and the error mentions port 8000 already being in use, another program on your machine is holding that port. This is common if you previously started Aurelio Finance and it did not shut down cleanly, or if another local dev tool grabbed the port.
Fix it:
- On Windows, run
netstat -ano | findstr:8000in Command Prompt to find the process ID using the port. On macOS/Linux, runlsof -i:8000. - Check whether that process is an old Aurelio Finance instance. If it is, you can simply stop it.
- On Windows, stop it with
taskkill /PID <process-id> /F. On macOS/Linux, usekill <process-id>. - Start Aurelio Finance again with the start script.
If you would rather not kill the other program, check whether the start script accepts a port flag to run on a different port. Either way, two programs cannot share port 8000, so one of them has to move.
PowerShell Execution Policy Blocks the Start Script (Windows)
On Windows, running .\start.ps1 may fail with an error about scripts being disabled on the system. This is PowerShell’s execution policy doing its job: by default, Windows blocks unsigned local scripts from running.
You have two safe options:
- Run it for just this session. Open PowerShell and run
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass, then run.\start.ps1in the same window. The policy change only lasts until you close that window, which keeps your system default intact. - Allow local scripts for your user account. Run
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned. This permits scripts you wrote or downloaded locally while still blocking unsigned scripts from the internet, and it persists across sessions.
Do not set the machine-wide policy to Unrestricted. The scoped options above are enough and leave the rest of your system’s protection alone. If your computer is managed by an employer or school, the policy may be locked by group policy; in that case use start.sh under Git Bash or WSL instead, or ask your IT admin.
Demo Mode vs Real Data: “Where Did My Data Go?”
This one causes brief panic. Aurelio Finance has a demo mode, started with ./start.sh --demo (or .\start.ps1 -Demo on Windows), which loads sample data so you can explore the app. If you start in demo mode after previously entering real data, your real data appears to be gone. It is not.
What is happening:
- Demo mode loads a sample dataset instead of your real
backend/data.db. Your real database file is untouched on disk. - Starting normally (without the
--demoflag) loads your real data again. - Anything you enter while in demo mode goes into the demo dataset, not your real records, so do not do real bookkeeping in a demo session.
Rule of thumb: use demo mode once to explore, then always start normally afterward. If the app ever looks “empty” unexpectedly, the first question to ask is which mode you started in.
The App Starts but Shows Errors or Blank Pages
If the server starts and http://localhost:8000 opens but pages are blank or show errors, the usual suspects are:
- Stale dependencies. If you updated the code with
git pull, the installed packages may be out of sync. Re-run the install steps from the project’s README, which refresh the Node and Python dependencies. - A half-finished first run. If the very first startup was interrupted (closed terminal, reboot), the database or asset build may be incomplete. Stop everything, delete any partially created build artifacts as the README describes, and start fresh. Your
backend/data.db, if it already held real data, should be left alone. - Browser cache. After an update, your browser may serve cached frontend files that no longer match the backend. Hard-refresh with Ctrl+Shift+R (Cmd+Shift+R on macOS) before assuming anything is broken.
- Antivirus interference. Some antivirus tools quarantine or block locally served apps on first run. If the app worked, then suddenly stopped after an antivirus update, check its quarantine log.
OpenRouter / AI Advisor Issues
Problems with the optional AI advisor are almost always key or billing issues, not app bugs. Run through this list:
- Invalid key. Double-check that you pasted the full OpenRouter API key with no extra spaces or line breaks. Keys are long; a truncated paste is the classic failure.
- No credits. OpenRouter is pay-per-use. If your OpenRouter account has no credits or the payment method failed, requests will be rejected. Check your balance on the OpenRouter dashboard.
- Wrong model or model unavailable. If you configured a specific model, confirm it is still available on OpenRouter. Model availability changes; fall back to a default model to test.
- Network or firewall blocking. The AI feature needs outbound HTTPS to OpenRouter. Corporate firewalls and some VPNs block it. Test with the VPN off or on a different network.
Remember that the AI advisor is entirely optional. If it is misbehaving and you just want to use the app, turn the feature off and everything else keeps working. You can revisit the AI setup later without losing any data.
The Nuclear Option: Reinstall From Source
If nothing above helps, a clean reinstall fixes nearly everything. The key insight: your data is separate from the code, so you can reinstall the app without losing your records.
- Back up your data first. Copy
backend/data.dbsomewhere safe, like your Documents folder or an external drive. This is the one step you must not skip. - Stop the app completely and close the terminal.
- Rename the old project folder (for example, to
aurelio-finance-old) instead of deleting it. If the reinstall fails, you still have everything. - Clone a fresh copy from GitHub and run through the install steps in the README from scratch.
- Verify the fresh install starts and opens http://localhost:8000 correctly.
- Copy your backed-up
data.dbinto the newbackend/folder, replacing the fresh empty one, then restart. Your data should be back exactly as you left it.
If the fresh install works but your old database does not load, try the automatic backup copy the app saved next to it, then your external backup.
Getting More Help
When you have tried the above and are still stuck, the project’s GitHub issue tracker is the right place to ask. A good bug report gets you help much faster:
- Your operating system and version (Windows 11, macOS 15, Ubuntu 24.04, and so on).
- The output of
git --version,node --version, anduv --version. - The exact error message, copied as text, not a screenshot of half of it.
- What you were doing when it broke (first install, after
git pull, enabling the AI advisor, and so on). - Whether demo mode works while normal mode does not, or vice versa. That detail narrows things down enormously.
Most “not working” reports turn out to be one of the issues above: an old Node.js, a port conflict, the execution policy, or demo-mode confusion. Work the list in order, keep your data.db backed up, and you will spend minutes on fixes instead of hours on frustration.
Conclusion
Troubleshooting Aurelio Finance is mostly about the environment around it, not the app itself. Verify Git, Node.js 22+, and uv first. Free up port 8000 if it is taken. Handle the PowerShell execution policy with a scoped change. Remember which mode you started in before panicking about missing data. And when all else fails, reinstall the code fresh while your backed-up data.db keeps your records safe. Local-first software puts you in charge, and these fixes are the small price of that control.
Read next:

Pingback: Back Up and Move Your aurelio finance Data