Troubleshooting

Diagnose from the server outward: process and health, authentication, project path, credential, then client rendering.

Server unreachable

1. Read the native tray/status, service manager, or docker compose ps.

2. Find the actual port. A release can fall back from 50505 to 50506–50514 or an OS-assigned port; native installs write port.txt in the application-data directory.

3. Call the health endpoint on that port:

   curl --fail-with-body http://localhost:50505/api/health

4. From another machine, test the public origin and firewall/reverse proxy, not localhost.

5. In the desktop app, return to server connection and test the origin without /api.

If the health call succeeds locally but not remotely, focus on firewall, proxy, DNS, TLS, and WebSocket forwarding. If it fails locally, inspect server logs and the service/container exit status.

Wrong or stale desktop server

The desktop app remembers recent origins and can discover a local native server from port.txt. Use the connection/login screen to choose another server. Do not delete server data merely to clear a client URL.

When desktop and server major versions are incompatible, update the older component. They have separate update flows.

Server will not start

Port conflict

Normally Stib falls back automatically. If every fallback fails, inspect which process reserves the range and whether OS/container policy prevents an assigned port. Do not run two Stib servers against the same data directory.

Data permissions

The server process must read and write its application-data directory and every project repository. In Docker, /data and repository mounts must be writable by the image's non-root user. Prefer fixing ownership/mount policy over running the container as root.

Migration or database error

Keep the original log and exact release version. Restore the official package/image if migration files were modified. Never edit an already applied migration to make a hash error disappear.

Use the in-app backup flow while the server is healthy. For offline SQLite diagnostics, stop every process using the database and work on a copy; do not run repair commands against a live production file.

Server stops right after an update

A new version backs the database up before migrating it; the last lines of the log say which step stopped the start-up (see Backups before migrations):

• "the database was restored to its pre-update state" — a migration failed and was undone. Nothing to repair: reinstall the previous version, or wait for a fixed release.
• "the pre-migration backup failed" — nothing was migrated. Free disk space (the backup needs about 1.3 times the size of the database), or set STIB_SKIP_PRE_MIGRATION_BACKUP=1 for one start.
• "the automatic rollback failed too" — the log names the backup in data/backups/. With the server stopped, delete data/stib.db-wal and data/stib.db-shm, then decompress the backup over the database: zstd -d -f data/backups/<backup> -o data/stib.db. If a backup key is configured, the file is encrypted: move the damaged database aside, start the previous version on an empty one, and restore the backup from Settings → Server → Backup.

Agent does not start

Check, in order:

1. card is in an active column and not deferred, locked, archived, or already running;
2. project repository path is accessible from the server;
3. selected credential is visible in that scope, valid, unlocked, and has quota/model access;
4. provider runtime/capability is detected;
5. worktree can be created and the repository has no blocking Git condition;
6. sandbox is available if the project requires it;
7. server logs contain the process-spawn error.

Retry only after fixing the cause. Repeated OAuth/quota failures can lock or rate-limit an otherwise recoverable credential.

Agent is waiting or appears stuck

Open Conversation and History. It may be waiting for a question, plan approval, queued message, provider response, script, automation condition, or loop schedule. The global Agents hub shows waiting conversations across projects.

If cancellation is necessary, inspect Diff/Git afterward. A process can write files before it becomes unresponsive.

Git or worktree failure

• Confirm the project points to the intended repository and the server user can run Git there.
• Refresh the Git workspace and inspect untracked/unstaged changes.
• Check branch/worktree collisions and whether another process uses the directory.
• Verify SSH keys, known_hosts, remotes, and provider CLI authentication for fetch/push/PR operations.
• Do not force cleanup of a worktree containing work you have not preserved.

Authentication and OIDC

• 401: missing/expired session or API token; reconnect or sign in again.
• 403: authenticated but missing seat, role, project scope, API permission, or licensed feature.
• OIDC callback failure: verify public STIB_SERVER_ORIGIN, exact callback registered at the IdP, HTTPS, issuer discovery, client ID/secret, scopes, and server clock.
• An API key only works on project-scoped routes allowed by its permission list and the access of its owning account. Use a dedicated low-privilege owner for external automation.

Keep one tested super-admin recovery path before changing sign-in methods.

WebSocket disconnects

The board can load over HTTP while live events fail if a reverse proxy does not forward WebSocket upgrades or has an aggressive idle timeout. Check the browser/desktop network log, proxy upgrade headers, TLS chain, and server logs. Reconnection should recover current server state; it does not duplicate the agent process.

Integrations fail

Run the integration connection test, then inspect mapping and sync status. The server/container—not the desktop—must resolve and reach the provider URL. Private/loopback targets are blocked unless the operator intentionally enabled STIB_ALLOW_PRIVATE_URLS.

Check provider permissions, rate limits, pagination, webhook delivery, and which side owns each mapped field.

Logs and support bundle

• Native server: application-data directory, below data/logs, or View/Export server logs from the tray.
• Docker: docker compose logs stib plus configured log export.
• Desktop: use the native desktop-log export/reveal action.
• Product activity: project/organization audit log.

Record client version, server version, installation type, actual origin/port, timestamp/time zone, affected project/card IDs, and steps to reproduce. Remove tokens, API keys, credential payloads, private prompts, and source content that is not required.