Start with Logs in the SoAI WebUI. Choose the Core or affected plugin source,
select the line count, and reproduce the problem. If you need the files directly, the main log path comes from
OBSERVABILITY.LOGGING.LOGS_PATH
and
OBSERVABILITY.LOGGING.MAIN_LOG. Security events use the audit log. The HTTP API reference documents the status and health
endpoints for scripted diagnostics.
Startup and access issues
403 "setup_required" means no users exist in the database yet. SoAI returns this on protected API
endpoints until someone creates the first account in the setup wizard. If you see it after a factory reset or on a
fresh install, open the SoAI WebUI and go through the wizard. If you see it after a database restore, the restore
may have failed or pointed at the wrong file. Check
DATA.DATABASE.PATHS.SYSTEM_DB. To inspect it there, an administrator with Configuration changes (CONFIG_PATCH) selects the Settings button at the right of the header, chooses Settings,
selects Advanced in the page header, then opens Data and finds
System db in the Paths group.
401 on /api/v1/* means the request is missing a valid WebUI session. Sign in and
retain the auth and CSRF cookies returned for your transport. HTTP uses soai-http-token and
soai-http-csrf; HTTPS uses __Host-soai-token and __Host-soai-csrf. Mutating
requests must also send the CSRF cookie value in X-SoAI-CSRF. Wizard status, login, and health are
among the public routes. See Authentication and API keys for the management-session
and compatible-API boundaries.
When a realtime connection fails during sign-in recovery, SoAI checks whether the current session is still valid. A confirmed expired session returns you to sign-in. A temporary network failure keeps your identity and retries the connection; it does not require signing in again. A permission rejection requires checking your account's access permissions.
401 on /v1/* means the compatible client endpoints require a SoAI API key
and one was not provided, or the token was wrong. After setup, these endpoints are open while the API-key store is
empty. The 401 appears after you create at least one API key inside SoAI. If you did not intend to enable key authentication, an administrator with
API key management (OPENAI_API_ADMIN) selects the Settings button at the right of the header, chooses
Settings, selects OpenAI, then selects Delete for each key that
should no longer exist. Review Authentication and API keys before changing the
instance-wide key policy.
SoAI won't start. Run the launcher for the installed edition and read its bootstrap output. Use
./soai.sh --debug for Core or ./soai_os/soai_os.sh --debug for SoAI OS. The
Windows launcher has no terminal of its own, so it reports a failed
start in its window and writes the same detail to data\state\launcher-startup-error.txt under the
installation folder; read that file when the window closes before you can. Common causes include starting SoAI
without its launcher, port 5090 already being in use, an incomplete managed runtime, or missing dependencies while
SYSTEM.RUNTIME.STAY_OFFLINE is
enabled. If the configured port is occupied, change
SERVER.HTTP.NETWORK.PORT in the
active configuration file. To repair the runtime, stop SoAI and run install-deps through the same
edition launcher. The Launcher and CLI reference gives the exact
commands and configuration-path rules.
If the Windows launcher cannot recover an interrupted update, close other SoAI windows and try again. If recovery still fails, keep the installation and its recovery files for repair. When setup asks you to restart Windows after a failed installation or cleanup, do that before running setup again.
SoAI takes several minutes to answer after a crash or power loss. A start that follows an unclean shutdown verifies the core database before the application serves anything, and that verification reads the whole file, so a large instance can spend minutes with no WebUI and no API. The lifecycle log states that the previous run did not shut down cleanly and reports the check as it finishes. Let it run: stopping SoAI or power-cycling the host during the check means the next start finds an unclean shutdown again and starts the same check over. After an unclean shutdown describes the behavior, including the GPU settings that the same start returns to safe defaults.
Plugin and inference failures
Requests fail for one plugin but others work. Open Plugins and select the affected plugin. Read its status and circuit-breaker details, then inspect that plugin's output in Logs. An open circuit blocks new dispatch after three consecutive qualifying failures by default. The Resilience and self-healing page explains the state transitions. A Quarantined status means the Guardian exhausted plugin recovery or a clone integrity check failed. Correct the reported cause, then follow Recover an unavailable plugin.
503 Service Unavailable with a queue-full error means the task queue is full. The default queue size is 1000 requests (MODELS.ROUTING.TASK_QUEUE_MAX_SIZE). Either your backends cannot keep up with the request rate or all plugins are down. Check the backlog size in the
system status and whether any plugins are processing.
Backend installation reports a missing executable. Update SoAI and retry the backend installation. Linux ROCm installation includes both the base engine and its matching accelerator libraries. The failed attempt leaves existing models available for the next attempt.
Model loading fails with VRAM errors. The backend enforces its own VRAM limits. When Ollama or vLLM runs out of GPU memory during model loading, the error bubbles up through the plugin as a backend-specific message. To lower plugin concurrency, open Plugins, select Configure concurrent plugins, lower Maximum concurrent plugins, and select Save. Select Restart SoAI when prompted. You can also use a smaller quantization or reduce the model's context length. Use Scheduler and runtime tuning for the concurrency controls, Capacity planning to size the host, Make SoAI faster on low-end servers to reduce unrelated host work, and GPU controls and tuning only after confirming the hardware path.
Model download fails. HTTP 507 means there is not enough disk space. HTTP 403 can mean that offline
mode is blocking the download (SYSTEM.RUNTIME.STAY_OFFLINE
is enabled). Network failures from the model source are recorded in the affected plugin log. Read the HTTP status
or diagnostic message available there. For HuggingFace models that require authentication, set
MODELS.CREDENTIALS.HUGGINGFACE_TOKEN
in Settings, Advanced, and Models. To use a plugin-specific token,
open Plugins, select Edit configuration for the affected plugin, set
DOWNLOADER_HF_TOKEN, then select Save. The
Models catalog owns download, registration, and provider workflows.
SoAI retries temporary download failures and can resume a transfer when its source supports it. Authentication failures, invalid files, and other permanent errors need corrective action. To replace an installed CTranslate2 model, delete it before starting another download.
WebUI and realtime issues
WebUI shows stale data. Live updates use the WebSocket at /api/v1/system/ws without a
polling fallback. If a reverse proxy, firewall, or load balancer blocks the connection, the UI marks retained data
as stale or disconnected. Check the browser console for WebSocket errors; for Nginx, confirm that the proxy forwards
the WebSocket upgrade and does not impose a short idle timeout.
Terminal not available. An administrator with Configuration changes (CONFIG_PATCH) selects the
Settings button at the right of the header, chooses Settings, selects
Advanced in the page header, opens Server, and enables
SERVER.WEBUI.TERMINAL.ENABLED. The user must also have Terminal and shell access (TERMINAL_USE), which is
admin-only by default. Continue with Terminal for access, session, and transport
details.
WebUI does not load. If the page shows Failed to Initialize SoAI WebUI, check that SoAI is running and reachable, then select Reload page.
Skill imports and loading
| Symptom | What to check |
|---|---|
| A named request is refused | Check the exact manifest name, enable the skill in Chat configuration > Skills, and save. The author must allow explicit requests. See Use a skill. |
| The assistant does not load a skill automatically | Check its availability label, tools enabled, a nonempty tool selection for the active mode, and model tool-calling support. Request a directly invocable skill by name when needed. |
| Instructions cannot fit in context | While idle, compact older context, use a larger-context model, or shorten the skill. No partial instructions are applied. |
| An import is rejected | WebUI imports require MCP_USE. Check Creating a skill for manifest and archive rules, and Imports and limits for capacity. Removed packages can remain retained while accepted work uses them. |
| The selection cannot be saved | Wait for reconnection. If another tab changed the selection, review the conflict before refreshing or keeping your draft. |
| A supporting script is missing from the workspace | Import does not install scripts. Select skill_materialize under Tools > Execute, save, and approve the assistant’s copy request. Use an allowed execution tool as described in Supporting files and context. |
Where to look
Use Dashboard for overall health, Plugins for plugin and circuit state, Tasks for operation status, and Logs for Core or plugin output. Select the Settings button at the right of the header, choose Settings, then select Advanced in the page header to expose Core configuration. The Configuration explains the active YAML file, factory defaults, and reset behavior. Use the System API status endpoint when a script needs the full orchestrator, plugin, circuit, and queue snapshot.