Troubleshooting

中文

Debug by layer. Do not change random config before locating the failing layer.

Diagnostic Order

Process: is the service alive, any panic?
Network: port, HTTPS, reverse proxy, browser console.
Auth: does /api/auth/validate return 200?
Config: can /api/config be read and applied?
Model: does model test pass?
Tools: do tool list and schemas look right?
Database: is data/ writable, any lock?
Subsystem: KB, MCP, C2, WebShell minimal action.

Minimal Commands

lsof -i :8080
curl -k -I https://127.0.0.1:8080/
curl -k -I https://127.0.0.1:8080/static/logo.png
ls -lh data/

If a reverse proxy is involved, test both proxy address and upstream address.

Common Issues

Page inaccessible:

wrong protocol, especially HTTPS vs HTTP;
self-signed cert warning;
port occupied;
reverse proxy loop.

wrong RBAC user password;
config not applied/restarted;
stale cookie;
audit throttling repeated failures.

Recover a forgotten `admin` password

If another administrator with rbac:write is available, reset the password under Platform permissions → User management.

If no administrator session is available, the built-in admin account can be recovered on the server. Stop CyberStrikeAI, back up the database, change to the project root, and run the command below. Enter and confirm the new password when prompted:

HASH=$(htpasswd -nBC 10 '' | cut -d: -f2 | tr -d '\n') && sqlite3 data/conversations.db "UPDATE rbac_users SET password_hash='$HASH', updated_at=CURRENT_TIMESTAMP WHERE id='admin' AND username='admin' AND is_builtin=1; SELECT changes();"

Output 1 means that the row was updated. The command requires sqlite3 and htpasswd. If database.path in config.yaml is not the default, replace data/conversations.db. Password input is hidden, is not written to shell history, and is stored as a bcrypt hash. Restart the service afterward to invalidate existing login sessions.

Model fails:

wrong base_url path;
invalid API key;
model unavailable;
reasoning fields unsupported by gateway. Try openai.reasoning.mode: off.

Streaming stalls:

proxy buffers SSE;
model gateway timeout;
context too large;
browser/network interruption.

Tool fails:

real command not installed;
YAML schema wrong;
HITL rejected or pending;
timeout or no-output timeout.

Knowledge base empty:

knowledge.enabled false;
scan/index not run;
embedding API failed;
threshold or risk type too strict.

C2 returns 503:

expected when c2.enabled: false.

Common Misdiagnoses

"Model is broken": HITL is waiting.
"Tool missing": tool_search hides it from current context.
"Knowledge base useless": index not rebuilt or risk type too narrow.
"Config saved but ineffective": listener/TLS changes need restart.
"Robot silent": platform callback or signature config wrong.

Issue Template

Version:
Startup method:
Access path:
Relevant config:
Steps:
Expected:
Actual:
Server logs:
Browser console:
API response:

3.1 KiB Raw Blame History