Failing to start openSAK after forking project

[urs-beeli]

As I have created a number of bug reports I thought I'd see if I could contribute some bug fixes. I followed the instructions under https://github.com/OpenSAK-Org/OpenSAK/blob/main/CONTRIBUTING.md

I have succesfully done the following steps:

Fork the repository

• (/) Clone your fork and check out beta: git clone --branch beta https://github.com/YOUR_USERNAME/opensak.git
• (/) Create a branch off beta: git checkout -b feature/my-feature
• (/) cd opensak
• (/) python -m venv .venv # using python instead of python3, because I don't have python3 on my path and "python --version" reports 3.14.6
• (/) .venv\Scripts\activate # Windows
• (/) pip install -e ".[dev]" # runtime + test deps (single source: pyproject.toml)
• (/) pytest -v tests/ # run tests

However, when I try to start opensak locally with this command:

• (x) python run.py # start the application

It fails with the following error messages that don't really tell me what I need to do to get openSAK up and running locally. Can anyone help me with this?

`
(.venv) d:\Daten\Programming\OpenSAK>python run.py
Traceback (most recent call last):
File "d:\Daten\Programming\OpenSAK.venv\Lib\site-packages\sqlalchemy\engine\base.py", line 144, in init
self._dbapi_connection = engine.raw_connection()
~~~~~~~~~~~~~~~~~~~~~^^
File "d:\Daten\Programming\OpenSAK.venv\Lib\site-packages\sqlalchemy\engine\base.py", line 3319, in raw_connection
return self.pool.connect()
~~~~~~~~~~~~~~~~~^^
File "d:\Daten\Programming\OpenSAK.venv\Lib\site-packages\sqlalchemy\pool\base.py", line 448, in connect
return _ConnectionFairy._checkout(self)
~~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^
File "d:\Daten\Programming\OpenSAK.venv\Lib\site-packages\sqlalchemy\pool\base.py", line 1272, in _checkout
fairy = _ConnectionRecord.checkout(pool)
File "d:\Daten\Programming\OpenSAK.venv\Lib\site-packages\sqlalchemy\pool\base.py", line 712, in checkout
rec = pool._do_get()
File "d:\Daten\Programming\OpenSAK.venv\Lib\site-packages\sqlalchemy\pool\impl.py", line 178, in _do_get
with util.safe_reraise():
~~~~~~~~~~~~~~~~~^^
File "d:\Daten\Programming\OpenSAK.venv\Lib\site-packages\sqlalchemy\util\langhelpers.py", line 122, in exit
raise exc_value.with_traceback(exc_tb)
File "d:\Daten\Programming\OpenSAK.venv\Lib\site-packages\sqlalchemy\pool\impl.py", line 176, in _do_get
return self._create_connection()
~~~~~~~~~~~~~~~~~~~~~~~^^
File "d:\Daten\Programming\OpenSAK.venv\Lib\site-packages\sqlalchemy\pool\base.py", line 389, in _create_connection
return _ConnectionRecord(self)
File "d:\Daten\Programming\OpenSAK.venv\Lib\site-packages\sqlalchemy\pool\base.py", line 674, in init
self.__connect()
~~~~~~~~~~~~~~^^
File "d:\Daten\Programming\OpenSAK.venv\Lib\site-packages\sqlalchemy\pool\base.py", line 914, in __connect
)._exec_w_sync_on_first_run(self.dbapi_connection, self)
~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "d:\Daten\Programming\OpenSAK.venv\Lib\site-packages\sqlalchemy\event\attr.py", line 502, in _exec_w_sync_on_first_run
self(*args, **kw)
~~~~^^^^^^^^^^^^^
File "d:\Daten\Programming\OpenSAK.venv\Lib\site-packages\sqlalchemy\event\attr.py", line 514, in call
fn(*args, **kw)
~~^^^^^^^^^^^^^
File "d:\Daten\Programming\OpenSAK\src\opensak\db\database.py", line 51, in _enable_wal_and_fk
cursor.execute("PRAGMA journal_mode=WAL")
~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^
sqlite3.DatabaseError: file is not a database

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
File "d:\Daten\Programming\OpenSAK\run.py", line 16, in
main()
~~~~^^
File "d:\Daten\Programming\OpenSAK\src\opensak\app.py", line 249, in main
manager.ensure_active_initialised()
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^^
File "d:\Daten\Programming\OpenSAK\src\opensak\db\manager.py", line 192, in ensure_active_initialised
init_db(db_path=self._active.path)
~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "d:\Daten\Programming\OpenSAK\src\opensak\db\database.py", line 112, in init_db
Base.metadata.create_all(new_engine)
~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^
File "d:\Daten\Programming\OpenSAK.venv\Lib\site-packages\sqlalchemy\sql\schema.py", line 5930, in create_all
bind._run_ddl_visitor(
~~~~~~~~~~~~~~~~~~~~~^
ddl.SchemaGenerator, self, checkfirst=checkfirst, tables=tables
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
)
^
File "d:\Daten\Programming\OpenSAK.venv\Lib\site-packages\sqlalchemy\engine\base.py", line 3269, in _run_ddl_visitor
with self.begin() as conn:
~~~~~~~~~~^^
File "C:\Python314\Lib\contextlib.py", line 141, in enter
return next(self.gen)
File "d:\Daten\Programming\OpenSAK.venv\Lib\site-packages\sqlalchemy\engine\base.py", line 3259, in begin
with self.connect() as conn:
~~~~~~~~~~~~^^
File "d:\Daten\Programming\OpenSAK.venv\Lib\site-packages\sqlalchemy\engine\base.py", line 3295, in connect
return self._connection_cls(self)
~~~~~~~~~~~~~~~~~~~~^^^^^^
File "d:\Daten\Programming\OpenSAK.venv\Lib\site-packages\sqlalchemy\engine\base.py", line 146, in init
Connection._handle_dbapi_exception_noconnection(
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^
err, dialect, engine
^^^^^^^^^^^^^^^^^^^^
)
^
File "d:\Daten\Programming\OpenSAK.venv\Lib\site-packages\sqlalchemy\engine\base.py", line 2450, in _handle_dbapi_exception_noconnection
raise sqlalchemy_exception.with_traceback(exc_info[2]) from e
File "d:\Daten\Programming\OpenSAK.venv\Lib\site-packages\sqlalchemy\engine\base.py", line 144, in init
self._dbapi_connection = engine.raw_connection()
~~~~~~~~~~~~~~~~~~~~~^^
File "d:\Daten\Programming\OpenSAK.venv\Lib\site-packages\sqlalchemy\engine\base.py", line 3319, in raw_connection
return self.pool.connect()
~~~~~~~~~~~~~~~~~^^
File "d:\Daten\Programming\OpenSAK.venv\Lib\site-packages\sqlalchemy\pool\base.py", line 448, in connect
return _ConnectionFairy._checkout(self)
~~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^
File "d:\Daten\Programming\OpenSAK.venv\Lib\site-packages\sqlalchemy\pool\base.py", line 1272, in _checkout
fairy = _ConnectionRecord.checkout(pool)
File "d:\Daten\Programming\OpenSAK.venv\Lib\site-packages\sqlalchemy\pool\base.py", line 712, in checkout
rec = pool._do_get()
File "d:\Daten\Programming\OpenSAK.venv\Lib\site-packages\sqlalchemy\pool\impl.py", line 178, in _do_get
with util.safe_reraise():
~~~~~~~~~~~~~~~~~^^
File "d:\Daten\Programming\OpenSAK.venv\Lib\site-packages\sqlalchemy\util\langhelpers.py", line 122, in exit
raise exc_value.with_traceback(exc_tb)
File "d:\Daten\Programming\OpenSAK.venv\Lib\site-packages\sqlalchemy\pool\impl.py", line 176, in _do_get
return self._create_connection()
~~~~~~~~~~~~~~~~~~~~~~~^^
File "d:\Daten\Programming\OpenSAK.venv\Lib\site-packages\sqlalchemy\pool\base.py", line 389, in _create_connection
return _ConnectionRecord(self)
File "d:\Daten\Programming\OpenSAK.venv\Lib\site-packages\sqlalchemy\pool\base.py", line 674, in init
self.__connect()
~~~~~~~~~~~~~~^^
File "d:\Daten\Programming\OpenSAK.venv\Lib\site-packages\sqlalchemy\pool\base.py", line 914, in __connect
)._exec_w_sync_on_first_run(self.dbapi_connection, self)
~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "d:\Daten\Programming\OpenSAK.venv\Lib\site-packages\sqlalchemy\event\attr.py", line 502, in _exec_w_sync_on_first_run
self(*args, **kw)
~~~~^^^^^^^^^^^^^
File "d:\Daten\Programming\OpenSAK.venv\Lib\site-packages\sqlalchemy\event\attr.py", line 514, in call
fn(*args, **kw)
~~^^^^^^^^^^^^^
File "d:\Daten\Programming\OpenSAK\src\opensak\db\database.py", line 51, in _enable_wal_and_fk
cursor.execute("PRAGMA journal_mode=WAL")
~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^
sqlalchemy.exc.DatabaseError: (sqlite3.DatabaseError) file is not a database
(Background on this error at: https://sqlalche.me/e/20/4xp6)
`

[AgreeDK]

Hi @urs-beeli, thanks for trying to contribute — and sorry for the rough start!

Good news: this isn't actually a problem with your clone or the setup steps you followed — everything up to pytest worked correctly. The error is happening in a file outside the repo entirely: OpenSAK's user database, which on Windows lives at %APPDATA%\opensak\Default.db.

What's going on:
On first launch, OpenSAK tries to open (or create) that database file and immediately runs PRAGMA journal_mode=WAL on it — that's exactly where your traceback fails, with "file is not a database". A truly new/non-existent file would never trigger this error (SQLite treats an empty file as a valid new database), so this tells us there's already a file at that path that isn't valid SQLite — likely partially written, empty-but-not-zero-bytes, or corrupted, possibly by antivirus real-time scanning interfering with the file while it was being created (we've seen similar AV interference with the database folder before, see #540).

Could you try this:

Close OpenSAK if it's running.
Open %APPDATA%\opensak\ in Explorer and check if Default.db exists — and how large it is.
Rename or delete that file (or the whole opensak folder — it'll just be recreated) and run python run.py again.
If it happens again, it'd be worth adding %APPDATA%\opensak\ to your antivirus exclusions, in case real-time scanning is interfering with the file while it's created.

If that doesn't fix it, could you also share:

The exact size (in bytes) of the pre-existing Default.db, if there is one
Whether you'd run any earlier version/build of OpenSAK on this machine before

One more thing worth noting: you're on Python 3.14.6, which is very new — we haven't specifically tested against it yet, so if the steps above don't resolve it, that could be a secondary factor worth ruling out.

Thanks again for digging into this — happy to keep troubleshooting with you!

[urs-beeli]

Thanks for explaining. Default.db existed (it was the database into which I had imported a 45'000 cache GSAK db) but something (maybe running the pytests while openSAK was still running) must have corrupted the file (3 tests failed, until I closed openSAK, then all of them passed). In any case, the file still existed but was only 1kb large and when I tried to start the binary openSak.exe it also failed. So I just deleted the file, restarted "python run.py" and now it started up nicely and I was already able to verify that my first bugfix worked ;-)

It's been years since I dabbled with python (and then only at a very basic level), so don't expect the huge feature additions, but if I can contribute a little here and there, it may be a chance to learn a bit more and contribute to our game (I guess that will be my contribution instead of writing GSAK macros, which I used to do...)

[AgreeDK]

Great to hear it's working now, and thanks for the detailed follow-up — that's actually a really useful clue! If running pytest while OpenSAK was still open against that same database was enough to corrupt it down to 1KB, that suggests our tests might not be fully isolated from the live user database in some edge case, rather than this being just a Windows/AV quirk. I'll dig into that on our end.

And no worries about the scope of contributions — small fixes and fresh eyes are exactly what helps a project like this, and if it's a fun way to stay connected to the game after years of GSAK macros, even better. Looking forward to seeing your first PR! 🎉