diff --git a/docs/getting-started/env-configuration.mdx b/docs/getting-started/env-configuration.mdx index fbfba2d65..d119419fa 100644 --- a/docs/getting-started/env-configuration.mdx +++ b/docs/getting-started/env-configuration.mdx @@ -2893,22 +2893,19 @@ This variable was introduced alongside a fix for **uvicorn worker death during d - Type: `str` - Default: `None` -- Description: Specifies the prefix for the RAG embedding content. -- Persistence: This environment variable is a `PersistentConfig` variable. +- Description: Sets the prefix string prepended to document content before generating embeddings. Some embedding models (e.g., nomic-embed-text) require task-specific prefixes to differentiate between content being stored vs. queries being searched. For nomic-embed-text, set this to `search_document: `. Only needed if your embedding model's documentation specifies a content/document prefix. -#### `RAG_EMBEDDING_PREFIX_FIELD_NAME` +#### `RAG_EMBEDDING_QUERY_PREFIX` - Type: `str` - Default: `None` -- Description: Specifies the field name for the RAG embedding prefix. -- Persistence: This environment variable is a `PersistentConfig` variable. +- Description: Sets the prefix string prepended to user queries before generating embeddings for retrieval. This is the counterpart to `RAG_EMBEDDING_CONTENT_PREFIX`. For nomic-embed-text, set this to `search_query: `. Only needed if your embedding model's documentation specifies a query prefix. -#### `RAG_EMBEDDING_QUERY_PREFIX` +#### `RAG_EMBEDDING_PREFIX_FIELD_NAME` - Type: `str` - Default: `None` -- Description: Specifies the prefix for the RAG embedding query. -- Persistence: This environment variable is a `PersistentConfig` variable. +- Description: Specifies the JSON field name used to pass the prefix to the embedding API request body. When set along with a prefix value, the prefix is sent as a separate field in the API request rather than being prepended to the text. Required for embedding APIs that accept the prefix as a dedicated parameter instead of inline text. #### OpenAI Embeddings diff --git a/docs/getting-started/quick-start/starting-with-openai-compatible.mdx b/docs/getting-started/quick-start/starting-with-openai-compatible.mdx index daa03f9e4..daa20ed51 100644 --- a/docs/getting-started/quick-start/starting-with-openai-compatible.mdx +++ b/docs/getting-started/quick-start/starting-with-openai-compatible.mdx @@ -43,18 +43,18 @@ There are many servers and tools that expose an OpenAI-compatible API. Pick whic Lemonade is a plug-and-play ONNX-based OpenAI-compatible server. Here’s how to try it on Windows: -1. [Download the latest `.exe`](https://github.com/lemonade-sdk/lemonade) +1. [Download the latest `.exe`](https://github.com/lemonade-sdk/lemonade/releases) 2. Run `Lemonade_Server_Installer.exe` 3. Install and download a model using Lemonade’s installer 4. Once running, your API endpoint will be: ``` - http://localhost:8000/api/v0 + http://localhost:8000/api/v1 ``` ![Lemonade Server](/images/getting-started/lemonade-server.png) -See [their docs](https://lemonade-server.ai/) for details. +See [their docs](https://lemonade-server.ai/docs/server/apps/open-webui/) for details. --- @@ -89,7 +89,7 @@ If running Open WebUI in Docker and your model server on your host machine, use ::: -##### **For Lemonade:** When adding Lemonade, use `http://localhost:8000/api/v0` as the URL. +##### **For Lemonade:** When adding Lemonade, use `http://localhost:8000/api/v1` as the URL. ![Lemonade Connection](/images/getting-started/lemonade-connection.png) diff --git a/docs/troubleshooting/manual-database-migration.md b/docs/troubleshooting/manual-database-migration.md index 16375e6f1..16861ef70 100644 --- a/docs/troubleshooting/manual-database-migration.md +++ b/docs/troubleshooting/manual-database-migration.md @@ -23,6 +23,12 @@ You need manual migration only if: - A developer has instructed you to run migrations manually ::: +:::tip Quick Fix: Migration Errors After Upgrading +**"No such table"** — Your migrations didn't apply. Enter your container, set the required environment variables ([see Step 2](#step-2-diagnose-current-state)), and run `alembic upgrade head`. See [details](#no-such-table-errors). + +**"Table already exists"** — A previous migration partially completed. You need to stamp the partially-applied migration and then upgrade. See [details](#table-already-exists-errors). +::: + :::danger Critical Warning Manual migration can corrupt your database if performed incorrectly. **Always create a verified backup before proceeding.** ::: @@ -410,6 +416,129 @@ INFO: [main] Open WebUI starting on http://0.0.0.0:8080 ## Troubleshooting +### "No such table" Errors + +**Symptom:** Open WebUI crashes on startup with an error like: + +``` +sqlalchemy.exc.OperationalError: (sqlite3.OperationalError) no such table: access_grant +``` + +or similar errors referencing other missing tables (e.g., `message`, `channel`). + +**Cause:** One or more Alembic migrations did not apply successfully. This can happen when: + +- A migration silently failed during an automated upgrade (Open WebUI logs the error but continues startup) +- The upgrade process was interrupted while migrations were running +- `ENABLE_DB_MIGRATIONS=False` was set in the environment (disables automatic migrations on startup) +- Multiple workers or replicas attempted to run migrations simultaneously + +:::warning ENABLE_DB_MIGRATIONS Does Not Fix This +Setting `ENABLE_DB_MIGRATIONS=True` (the default) only tells Open WebUI to **attempt** automatic migrations on the next startup. It will **not** retroactively fix migrations that already failed or were skipped. If your database is already in a bad state, you must apply the migrations manually. +::: + +**Solution:** + +Follow [Step 2](#step-2-diagnose-current-state) to access your environment, then run: + +```bash title="Terminal" +cd /app/backend/open_webui # Docker +alembic upgrade head +``` + +This will apply all pending migrations, including creating any missing tables. After a successful migration, restart Open WebUI normally. + +If you see additional errors during the manual migration (such as ["table already exists"](#table-already-exists-errors)), check the other troubleshooting sections below for specific error messages. + +### "Table Already Exists" Errors + +**Symptom:** Running `alembic upgrade head` fails with: + +``` +sqlalchemy.exc.OperationalError: (sqlite3.OperationalError) table chat_message already exists +``` + +or similar errors for other tables (e.g., `access_grant`). + +**Cause:** A previous migration **partially completed** — the table was created in the database, but Alembic's version tracking was not updated (typically because the migration was interrupted during the data backfill step that runs after table creation). Alembic still thinks the migration hasn't been applied, so it tries to create the table again. + +**Diagnosis:** + +```bash title="Terminal - Identify the Stuck Migration" +# Check where Alembic thinks you are +alembic current +# Example output: 374d2f66af06 (head) + +# Check what the next migration is +alembic history +# Look for the migration immediately after your current version +# Example: 374d2f66af06 -> 8452d01d26d7, Add chat_message table +``` + +**Solution:** + +There are three ways to resolve this, listed from safest to most lossy: + +#### Option 1: Restore from Backup (Recommended) + +Restore your database from the backup you created in [Step 1](#step-1-backup-your-database), then run `alembic upgrade head` on the clean backup. This guarantees the full migration — including all data backfills — completes correctly. + +#### Option 2: Drop the Table and Re-Run + +If you don't have a backup, you can drop the partially-created table and let the migration run from scratch. **Before doing this, verify it is safe:** + +```bash title="Terminal - Verify Before Dropping" +# 1. Confirm the migration is incomplete (current revision should be BEFORE the failing one) +alembic current + +# 2. Check how much data the table has (if any) +# SQLite: +sqlite3 /app/backend/data/webui.db "SELECT COUNT(*) FROM ;" +# PostgreSQL: +psql $DATABASE_URL -c "SELECT COUNT(*) FROM ;" + +# 3. Open the migration file and verify the source data still exists +# Find the file by its revision ID: +ls migrations/versions/ | grep +# Read it and look for which source columns/tables it copies FROM. +# Then verify those source columns still exist in your database. +``` + +Once you've confirmed the migration is incomplete and the source data is intact, drop the table and re-run: + +```bash title="Terminal - Drop and Re-Run" +# SQLite: +sqlite3 /app/backend/data/webui.db "DROP TABLE ;" + +# PostgreSQL: +psql $DATABASE_URL -c "DROP TABLE ;" + +# Re-run migrations +alembic upgrade head +``` + +:::caution Check the Migration File First +This is only safe if the migration **copies** data from old columns into the new table (the original data remains intact). Open the migration file and verify it uses `INSERT INTO ... SELECT FROM` or similar — **not** destructive operations that modify or delete the source data. If you're unsure, use Option 1 instead. +::: + +#### Option 3: Stamp Past It (Last Resort) + +If neither option above is possible, you can tell Alembic to skip the stuck migration entirely: + +```bash title="Terminal" +# Mark the migration as applied without running it +alembic stamp + +# Continue with remaining migrations +alembic upgrade head +``` + +:::warning This Skips the Data Backfill +Stamping marks the migration as done but skips any remaining steps like copying historical data into the new table. Your old data is **not deleted** — it still exists in the original columns — but the application may not read from those old columns anymore. Some features may work with gaps in historical data, while others may lose settings entirely. +::: + +If `alembic upgrade head` fails again with another "table already exists" error for a different migration, repeat the process for each stuck migration. + ### "Required environment variable not found" **Cause:** `WEBUI_SECRET_KEY` environment variable is missing. diff --git a/static/images/getting-started/lemonade-connection.png b/static/images/getting-started/lemonade-connection.png index 4683ab110..ca5e00790 100644 Binary files a/static/images/getting-started/lemonade-connection.png and b/static/images/getting-started/lemonade-connection.png differ