When the machine says no.
Sunni is intentionally simple, but it sits on top of several moving parts: the desktop shell, Open WebUI, Ollama, your model and the local browser profile. This page covers the failures we can identify and the remedies we actually know.
Sunni is the cockpit, not the engine.
Sunni 2.0 is a PySide6 desktop shell that opens your local Open WebUI
instance at http://localhost:8080. Open WebUI then communicates
with Ollama and the models installed through Ollama.
The ordinary mortal problems.
Start here. These are the failures most likely to happen during setup or first launch.
Sunni opens, but the main page is blank or refuses to connect. +
Sunni expects Open WebUI to exist at
http://localhost:8080. If nothing is serving that
address, Sunni has nothing to display.
Open http://localhost:8080 directly in your normal
web browser. If Open WebUI does not load there either, start or
repair Open WebUI first. Sunni cannot repair a missing endpoint.
Open WebUI loads, but there are no models available. +
A working Open WebUI interface does not automatically mean an Ollama model has been installed.
ollama list
If the list is empty, install a model through Ollama. Once Ollama has a model available, confirm that Open WebUI can see it before troubleshooting Sunni.
I downloaded the source version and ./launch.sh will not run.
+
The executable permission may have been lost when the archive was extracted.
chmod +x launch.sh
./launch.sh
Restore the executable bit with chmod +x launch.sh
and run the launcher again.
The source version says PySide6 or another Python dependency is missing. +
Launching the source directly with the system Python can bypass the environment Sunni expects.
./launch.sh --install-launch
Use Sunni's launcher to create the local .venv,
install the requirements and launch using that environment.
I switched to Private Browser mode and my login disappeared. +
That is expected. Private mode uses a separate off-the-record QWebEngine profile with memory cache and no persistent cookies or site storage.
Return to the persistent browser session in Sunni Settings if you want your saved Open WebUI login and site storage again.
I disabled persistence. Why is the old persistent data still there? +
Disabling persistence switches Sunni to a different private profile. It does not erase the existing persistent profile.
This is intentional. Re-enable persistence to return to the
existing stored session. If you specifically want to erase that
profile, close Sunni first and remove or archive the
data/web_profile/ directory.
You opened the hood.
These problems usually appear after modifying themes, rebuilding the source release or managing local application data.
I added or edited a theme, but Sunni still shows the old appearance. +
Sunni detects QSS themes from assets/css/, including
nested theme folders. The Reload control also re-scans the theme
directory and re-reads the currently selected stylesheet.
Save the .qss file, then press Reload
in Sunni. If it is a new theme, open Settings and select it from
the refreshed theme list.
A custom theme appears in the list but does not visibly change anything. +
Sunni applies the stylesheet only when the QSS file can be read and contains selectors that affect the existing interface.
Compare the custom theme against the included working QSS files and verify that it targets Sunni's actual object names and Qt widget selectors. A valid file with irrelevant selectors can load successfully while changing nothing.
My saved browser session behaves strangely after a long period of testing. +
Sunni's persistent QtWebEngine profile stores cache, cookies and
HTML5/site storage beneath data/web_profile/. A heavily
used development profile can accumulate stale browser state.
Close Sunni completely, rename
data/web_profile/ to something such as
web_profile.old/, then relaunch Sunni. It will create
a fresh profile automatically. Renaming instead of deleting
gives you a reversible test.
The source build fails before PyInstaller even starts. +
Sunni's build process first creates a Python virtual environment and installs the project requirements. If the system cannot create a venv, the build cannot proceed.
python3 -m venv .venv
Verify that your Linux installation provides Python's venv
support. Once python3 -m venv .venv works, rerun
./launch.sh --build.
The build completed. Where did the compiled application go? +
The included build workflow produces an onedir PyInstaller build, not a single-file executable.
dist/Sunni/Sunni
Run the compiled application from
dist/Sunni/Sunni. Keep the rest of the generated
dist/Sunni/ directory with it because the onedir
package contains supporting files.
I changed Sunni's browser-session setting but cannot find the settings file. +
Sunni does not ship with a pre-populated settings file. It creates one when a setting is saved.
data/settings.json
Look under Sunni's runtime data/ directory after
changing the browser-session persistence setting.
You have checked everything. It is still wrong.
At this level, stop restarting random components and isolate the failure one subsystem at a time.
Sunni is running, Open WebUI is running, Ollama is running, and the model still does not respond. +
At this point the desktop shell is no longer the useful place to begin diagnosis.
Test the chain independently. First use Open WebUI directly in
a normal browser at http://localhost:8080. If the
same model fails there, troubleshoot the Open WebUI/Ollama/model
connection. If it works there but not inside Sunni, then the
problem has been isolated to Sunni's embedded browser/session
layer.
Open WebUI works in my browser, but Sunni's embedded view is broken. +
That isolates the failure to the QtWebEngine side of Sunni rather than the AI backend.
Close Sunni, temporarily move data/web_profile/ out
of the way and relaunch. Sunni will create clean storage and cache
directories automatically. If the fresh profile works, the old
embedded browser profile was the variable.
I moved Open WebUI away from port 8080 and Sunni stopped finding it. +
Sunni 2.0 currently defines its Open WebUI address in the application
source as http://localhost:8080.
Run Open WebUI at localhost:8080, or in the source
edition change the WEBUI_URL value in
app.py to your intended endpoint and rebuild or
relaunch the source version.
I changed app.py, but the binary behaves exactly like the old version.
+
Editing source code does not modify an already-built PyInstaller package.
./launch.sh --build
Rebuild Sunni and run the newly generated
dist/Sunni/Sunni. The build script removes the old
build/ and dist/ directories before
creating the replacement.
I am preparing my own distribution. What should absolutely not be inside it? +
Sunni generates development and browser state that should not be redistributed as part of a clean source release.
.venv/
build/
dist/
__pycache__/
*.pyc
data/
Build your clean archive from the application source and assets,
not from a directory containing your active browser profile.
Sunni recreates its runtime data/ structure itself.
Nothing above matches my failure. +
Then it is not yet a known remedy, and pretending otherwise only converts one bug into two.
Reproduce the problem from a terminal, capture the exact error, identify whether it originates from Sunni, QtWebEngine, Open WebUI, Ollama or the model, and diagnose that specific component. The first useful error message outranks twenty guesses.
Test the chain in order.
Sunni → Open WebUI → Ollama → Model. Find the first component that does not work independently. That is where the problem begins.