Reference

Troubleshooting

Common errors and how to fix them.

Launcher (start.bat / start.sh)

"Could not install uv"

The launcher tried the astral.sh installer and uv still isn't on PATH — usually a network block or a terminal that hasn't picked up the new PATH yet. Install it by hand, then open a new terminal and re-run the launcher:

  • Windows: winget install astral-sh.uv or powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
  • macOS/Linux: brew install uv or curl -LsSf https://astral.sh/uv/install.sh | sh

uv downloads its own Python 3.11+ if the system one is missing or too old, so a "python is not recognized" error no longer blocks setup.

".venv not found! Run Full Install (option 2) first."

Quick Start was chosen before the environment was ever created. Run Full Install once, or manually:

uv sync

"The database "dbskms" doesn't exist on localhost:5432." (Quick Start, step 5)

Quick Start only updates an existing database; it doesn't create one. Either the database named in DATABASE_URL in .env was never set up on this machine, or the name is wrong. Run Full Install (option 2) once to create it with the demo accounts, or fix DATABASE_URL to name the database you already have.

"Can't reach PostgreSQL at localhost:5432" (Quick Start, step 5)

PostgreSQL isn't running. Start it (on Windows, the postgresql service, or open pgAdmin) and run Quick Start again.

"Docker Desktop didn't start within 3 minutes"

Quick Start tried to open Docker Desktop for you, but it didn't finish starting. Open Docker Desktop yourself, wait until it says the engine is running, then run Quick Start again.

"uv sync failed" during Full Install

Could be a network issue or a missing system dependency for a compiled package. Run it directly to see the full error:

uv sync

If the environment looks corrupted, delete it and let uv rebuild it:

rmdir /s /q .venv      # macOS/Linux: rm -rf .venv
uv sync

If the error mentions uv.lock being out of date with pyproject.toml, someone changed a dependency without re-locking — run uv lock and commit the result.

"Docker is not running"

Docker Desktop isn't started. Open Docker Desktop and wait for the green "Engine running" indicator. If Docker is installed but not starting:

  • Windows: restart your computer after installation
  • Ensure WSL2 is enabled (Windows)
  • Check virtualization is enabled in BIOS

"Docker services failed to start"

Run the command directly to see the actual error:

docker compose up minio redis onlyoffice

Common causes:

  • Port conflict — check if 9000, 9001, 6379, or 8080 are already in use
  • Insufficient disk space — Docker images need ~2 GB total
  • Hyper-V/WSL2 not properly configured (Windows)

Docker says "set ONLYOFFICE_JWT_SECRET in .env"

Since 2.0.0-beta.1, docker-compose.yml reads the editor secret from .env and stops if it is missing. Run start.bat / start.sh once, or uv run python scripts/ensure_secrets.py; either one writes a random ONLYOFFICE_JWT_SECRET into .env.

"Ollama is not installed"

Download and install from ollama.com. After installation, restart your terminal or command prompt so ollama is recognized.

Models failing to pull (qwen2.5:3b, nomic-embed-text, llava)

Try pulling manually, one at a time:

ollama pull qwen2.5:3b
ollama pull nomic-embed-text
ollama pull llava

If downloads are slow or time out, check your internet connection. The models total ~6-7 GB.

"Database setup failed"

Check:

  • PostgreSQL is running (open pgAdmin 4)
  • DATABASE_URL in .env has the correct password
  • Port 5432 is not blocked or in use

Try running the setup manually to see the full error:

venv\Scripts\activate
python scripts\setup_db.py

Launcher crashes immediately / doesn't show the menu

The script uses ANSI escape codes for colors. On very old Windows versions (pre-Windows 10) or PowerShell ISE, these may not render properly. Run from a standard Command Prompt or Windows Terminal. If the issue persists, open start.bat in Notepad and remove the color lines (near the top) or run the manual steps instead.

Database

"Could not connect to server: Connection refused"

PostgreSQL is not running. Open pgAdmin 4 to start it automatically.

"relation 'users' does not exist"

Tables not created yet. Run:

python scripts\setup_db.py

"type 'vector' does not exist"

pgvector not enabled. Run python scripts\setup_db.py (enables it automatically), or manually in pgAdmin's Query Tool on dbskms:

CREATE EXTENSION IF NOT EXISTS vector;

"Incorrect email or password"

Seed data not loaded. Run: python scripts\setup_db.py

Settings page loads forever / spinner never stops

GET /api/users (only called by Settings, listing every user) fails silently when any user row still has a dean or super_admin role from before the role-consolidation update — the current code doesn't recognize those roles anymore, so the request never completes. Every other page keeps working since none of them list all users.

Fix: run python scripts\setup_db.py — its "Legacy data" step migrates any leftover dean/super_admin rows to admin automatically. By hand:

UPDATE users SET role = 'admin' WHERE role::text IN ('dean', 'super_admin');

Python & Packages

"ModuleNotFoundError: No module named 'app'"

The command was run from the wrong folder, or with the system Python instead of the project environment. Run from the project root, through uv:

cd C:\Users\YourName\Downloads\SKMS
uv run python run.py

"ModuleNotFoundError: No module named 'sqlalchemy'" (or any other package)

The .venv is missing or out of date with uv.lock. start.bat / start.sh check for this and re-sync automatically in Quick Start mode, or fix manually:

uv sync

If you ran python run.py directly (without uv run), that used the system Python, which has none of the project's packages — always go through uv run.

bcrypt error

bcrypt is pinned to 4.0.1 in uv.lock on purpose (newer versions break passlib). If a different version has crept in, uv sync restores the pinned one.

Services

"MinIO not available" on startup

Docker is not running or MinIO stopped. Open Docker Desktop, then:

docker compose up -d minio

"Ollama offline" or chat gives an error

Ollama is not running:

ollama serve

If models aren't downloaded:

ollama pull qwen2.5:3b
ollama pull nomic-embed-text
ollama pull llava

AI answers are slow

Check whether Ollama uses a GPU: ollama ps shows 100% CPU when it doesn't. Ollama skips built-in graphics (AMD Radeon in Ryzen processors, Intel Arc/Iris) by default; its log says dropping integrated GPU; to enable, set OLLAMA_IGPU_ENABLE=1. To turn it on (Windows), quit Ollama from its tray icon, then:

setx OLLAMA_IGPU_ENABLE 1

Start Ollama again (from the Start menu, or sign out and in) and run ollama ps after a question: it should show 100% GPU. On the pilot laptop (Ryzen 7 170, 13.7 GB RAM) a chat answer over about 1,400 tokens of documents went from about 21 s on the CPU to about 9 s on its Radeon graphics: reading the documents got about 3× faster, writing the reply about 13% faster. If answers get slower instead, remove it with reg delete HKCU\Environment /v OLLAMA_IGPU_ENABLE /f and restart Ollama.

Memory matters as much: built-in graphics share system RAM, and when RAM is full Windows pushes the model out of memory and answers slow down. Close browsers, editors and games you don't need while SmartKMS serves people.

ONLYOFFICE editor doesn't open / "The document security token is not correctly formed"

The onlyoffice container is still running with an older secret than the one in .env (for example, it was created before you upgraded to 2.0.0-beta.1, or .env was edited since). Run start.bat / start.sh, or docker compose up -d onlyoffice, to recreate it with the secret from .env.

"SmartKMS's storage is full, so … can't be saved"

The upload would have left less than STORAGE_RESERVE_MB (512 MB) free where documents are stored: the server's disk for MinIO, the site's quota for SharePoint or OneDrive. Nothing was stored. An administrator can delete documents nobody needs and empty the Trash, or the server administrator can add space; administrators already see a red banner saying so. See Configuration for the warning and reserve settings.

Older documents don't open after switching storage

Their files are still in the previous storage (MinIO, say, after switching to SharePoint), which must keep running with its settings in .env. The startup log says how many files are there and whether it can reach them. Move them into the current storage with python scripts/move_files.py (see Configuration → Storage). Before 2.0.0-beta.21, previews of those files were also blocked by the browser after a switch; update if you're on an older version.

Search returns no results

Two things must be true: document uploaded, and the AI background task has finished generating the embedding — wait 30–60 seconds after upload.

Port 8000 already in use

Edit run.py and change port=8000 to port=8001, then visit http://localhost:8001

Document editor stuck loading forever, or "SignatureDoesNotMatch"

See Document Editing → Troubleshooting for the full breakdown.

Docker Deployment (Option 3)

"docker-compose.deploy.yml not found"

You're not in the project root, or the deploy file is missing. Make sure you're in the folder containing docker-compose.deploy.yml.

"DOMAIN is not set in .env.deploy"

Edit .env.deploy and set your domain (e.g., DOMAIN=skms.youruniversity.edu). Then re-run Option 3.

Certificates fail to issue (Caddy)

All three DNS records must point to this server's public IP before Caddy can issue certificates:

  • your-domain → server IP
  • files.your-domain → same server IP
  • office.your-domain → same server IP

Check with nslookup or dig before deploying.

AI stopped working after updating a Docker deployment

Since v2.0.0-beta.21 the bundled Ollama is the ollama compose profile. An .env.deploy from an older version has no COMPOSE_PROFILES line, so docker compose … up starts without it. Add COMPOSE_PROFILES=ollama to .env.deploy and run up -d again, or redeploy through start.bat / start.sh → Docker Deployment, which adds it for you. If you use an Ollama elsewhere instead, leave it empty and set OLLAMA_BASE_URL.

"Build failed" during Docker Deployment

Run the build command directly to see the error:

docker compose -f docker-compose.deploy.yml build --no-cache

Check Docker has enough memory allocated (at least 4 GB recommended).

On this page