Troubleshoot Knowledge Worker Agent
This guide shows you how to use Diagnostics, check whether Knowledge Worker Agent is healthy, find its log, and learn what common messages mean.
Look at Diagnostics
Diagnostics brings together what you need to troubleshoot a workspace, without opening a terminal. Users can open it themselves, and send you its report. For the steps users follow, see Get help with a problem.
To open it, select Settings (the gear icon) at the bottom of the sidebar, then Diagnostics. It has three tabs:
-
Overview: the Knowledge Worker Agent and opencode versions, the status and how long it has been running, the model providers with the Default and Thinking models under theirs, connectors, free disk space and folder sizes, the settings in effect, and where files are kept.
-
Configuration: the central configuration in use, and when it was applied. It also lists the user's own items hidden by assigned ones of the same name, and earlier default files kept because the user edited them. To apply a change without a restart, select Refresh configuration. For more information, see Apply a change without a restart.
-
Log: the newest lines of the Knowledge Worker Agent log or the opencode log. Show All lines or only Warnings and errors, search them, or select Download for the whole log.
Copy report copies the Overview and Configuration tabs to the clipboard as text, with recent warnings and errors from the log. Passwords, keys, and tokens are left out. Refresh reads everything again.
People you share a chat with can't open Diagnostics.
Check that it's running
Knowledge Worker Agent answers on its port,
8765 by default:
| Address | Answers |
|---|---|
/healthz |
ok while the server is running. |
/api/status |
status (starting or ready), and opencode_ready (true or false). |
For example, from inside the workspace:
curl -s http://127.0.0.1:8765/api/status
The server answers as soon as it starts, and prepares the rest in the background. Until
opencode_ready is true, chats can't run.
Check
opencode_ready, not only status. status becomes ready when startup finishes, even if opencode couldn't be installed.
The image's health check runs
/usr/bin/knowledge-worker-agent health, which checks /healthz.
Find the log
Knowledge Worker Agent writes its log to standard output and standard error, and copies it to
~/Knowledge_Worker_Agent/.system/logs/knowledge-worker-agent.log, where it's kept across restarts. A workspace that hasn't moved its files into one folder yet copies it to /tmp/chat-logs/chat.log. To use another file, set KWA_LOG_FILE. To stop the copy, set it to off.
Useful prefixes to search for:
| Prefix | Covers |
|---|---|
Central configuration |
Central configuration. |
MCP catalogue |
Adding and removing built-in connectors. |
[voice] |
Dictation. |
[workspace-heartbeat] |
The workspace heartbeat. |
[guest] |
Shared chats. |
[fileshare] |
Shared files, and making files self-contained. |
OpenCode |
Installing and running opencode, and loading models. |
One-folder migration |
Moving files into one folder, and moving them back. |
Settings with old names |
Settings set with a name from an earlier release. |
The log never contains dictation audio or transcripts.
Common problems
The log says "Settings with old names, which a later release stops reading"
Some settings are set with the name they had in an earlier release. They still work. The line lists each one with its new name, for example
COPILOT_WEB_PORT (now KWA_PORT). Rename them where you set them. SecurSpaces still sets some earlier names, so the warning is expected for now. For every name, see Environment variables.
Users see "Files can't move into one folder yet"
The workspace doesn't have enough free disk space to move its files into one folder. The banner says how much to free up. Nothing has changed. Free up the space, then restart the workspace. For more information, see Move files into one folder.
Knowledge Worker Agent shows "Reorganizing your files"
Knowledge Worker Agent is moving its files into one folder, or moving them back. It's unavailable until the move finishes, and
/api/status reports migrating. Don't stop or restart the workspace. If it stops anyway, nothing is lost. For more information, see Move files into one folder.
Users see "Some chats aren't shown"
An earlier release ran after the files moved into one folder, and created a database at the old place. Chats made there aren't shown. Before you go back to an earlier release, undo the move. For more information, see Go back to an earlier release.
Users see "Knowledge Worker Agent only opens what's in your home folder"
Knowledge Worker Agent opens files and folders only in the home folder, apart from the hidden folders and files directly in it, such as
.ssh and .config. A chat whose folder was chosen elsewhere in an earlier release keeps working, but the Files panel can't open its folder, and its files can't be shared. Mount points outside the home folder, such as /mnt/shared-data, can't be opened either, and a link to one from the home folder isn't followed. To work with those files, copy or move them into a folder in the home folder, for example from a terminal. Then start a chat there with Use existing folder.
Users see "Your workspace is almost out of disk space"
Less than 5% of the disk that holds the Knowledge Worker Agent folder is free. While it is,
/api/status reports disk, with the free and total space. When the disk is full, the assistant can't save files, and chats can fail.
Increase the workspace's storage in the SecurSpaces console, or free up space. Knowledge Worker Agent can't change the disk size itself: SecurSpaces changes a workspace's specification only in the console. To see which folders use the most space, open Diagnostics. For the steps users follow, see If your workspace is almost out of disk space.
Users see "Backend is restarting"
The page can't reach the server. It checks every few seconds, and reloads when the server is back. Check that the server is running, and look at the end of the log.
Chats don't start, and the log says "OpenCode bootstrap failed"
Knowledge Worker Agent couldn't install or run opencode. Check that the workspace can reach the npm registry,
registry.npmjs.org, or set KWA_OPENCODE_BIN to a working opencode binary. The release image includes a copy of opencode for workspaces that can't reach it. If the log says checksum mismatch, the download wasn't the release Knowledge Worker Agent is pinned to, so it wasn't installed.
Users see "No model provider is configured for this workspace."
No model provider is available. Without central configuration, users can connect one under Settings > Accounts. With
KWA_CENTRAL_CONFIG=true, assign a provider in the configuration repository. For more information, see Set up central configuration.
If the log says
KWA_CENTRAL_CONFIG is on but no config-declared provider resolved, none of the assigned providers could be used, so the built-in ones are offered instead. The message says why.
Central configuration isn't applied
Search the log for
Central configuration:
| Message | Meaning |
|---|---|
✓ Central configuration: project … |
Applied. The counts show what was written. |
skipped — no project id (KWA_PROJECT_ID unset) |
Set KWA_PROJECT_ID. |
skipped — no config repo (KWA_CONFIG_REPO_URL unset) |
Set KWA_CONFIG_REPO_URL. |
project "…" not found in assignment config |
Add the project under assignments in assignment.jsonc. |
assignment references unregistered artifacts |
Register each ID the message lists under artifacts. |
Config repo pull failed (…); using cached clone |
The repository couldn't be reached. The last cached copy was used. A workspace that has never reached the repository has no cached copy, so nothing is applied. Check the URL and the workspace's Git credentials. |
is a directory |
A context artifact points to a folder. Context must be a single file. This stops the whole run, so nothing is applied. Register each file on its own. |
If the workspace has no agents, context, or skills at all, check that
KWA_PROJECT_ID and KWA_CONFIG_REPO_URL are set as well as KWA_CENTRAL_CONFIG. With only KWA_CENTRAL_CONFIG on, nothing is applied.
Knowledge Worker Agent reads the repository only when it starts. Restart it to apply changes.
A provider shows Connected, but the first message fails
Connected means a key is stored, not that the key is valid. The model list comes from opencode's catalog, not from the provider, so an invalid key still lists models. The first turn then fails, for example with
Invalid API Key. Ask the user to check the key and add it again under Settings > Accounts.
A model provider is withheld as unreachable
The log says
authenticated provider(s) withheld as unreachable. A provider is signed in, but the workspace can't reach it. In Accounts, the provider shows "Signed in, but unreachable". Check the workspace's network access to that provider.
Dictation isn't offered
Check that
KWA_VOICE isn't set to a value that turns it off, and that the speech engine and model are installed. For their locations, see KWA_VOICE_BIN and KWA_VOICE_MODEL in Environment variables. For what the user's browser needs, see Dictation in Workspace requirements.