Troubleshooting

This guide helps you diagnose and resolve common issues with Stib. Each section covers symptoms, likely causes, and step-by-step solutions. See also Configuration for setup options, Authentication for SSO/OIDC details, System Tray for desktop integration, and Credentials & Scripts for credential management.

Diagnostic Basics

Before diving into specific issues, use these quick checks to assess the health of your Stib instance.

Check if the Server is Running

Send a request to the health check endpoint:

curl http://localhost:50505/api/health

A healthy server responds with:

{ "data": { "status": "ok" } }

If you get no response, the server is not running or not reachable on that address.

Verify the Port

Confirm that Stib is listening on the expected port:

# macOS / Linux
lsof -i :50505

# Windows
netstat -ano | findstr :50505

Check the Server Process

# macOS / Linux
ps aux | grep stib

# Windows
tasklist | findstr stib

Quick Database Check

Verify the database is accessible and not corrupted:

sqlite3 data/stib.db "PRAGMA integrity_check;"

A healthy database responds with ok.

Accessing Logs

Log File Location

Stib writes log files to the data/logs/ directory relative to the server's working directory. Files follow a daily rotation pattern:

data/logs/stib.YYYY-MM-DD.log

Up to 7 log files are retained. Older files are automatically deleted.

Real-Time Logs Page

The web UI includes a real-time logs page at /logs. It provides:

• Up to 500 recent log entries
• Level filter (DEBUG, INFO, WARN, ERROR)
• Free-text search with debounce
• Live streaming via WebSocket
• Expandable entries with fields and span context
• Connection status indicator (green = connected, red = disconnected)

Controlling Log Level

The default log filter is stib_server=info,tower_http=info. To increase verbosity, set the RUST_LOG environment variable:

RUST_LOG=stib_server=debug ./stib-server

Common log level values:

Value	Description
error	Errors only
warn	Errors and warnings
info	Normal operation (default)
debug	Detailed diagnostic information
trace	Very verbose, includes all internal details

Log Export & Aggregation

Stib supports exporting logs to external aggregation systems:

Format	Target System	Description
CLEF	Seq	Compact Log Event Format
GELF	Graylog	Graylog Extended Log Format
JSONL	Any endpoint	JSON Lines, one event per line

Export settings:

Setting	Range	Default	Description
batch_size	1–10,000	100	Events per batch
flush_interval_secs	1–300	5	Seconds between flushes

Failed exports are retried up to 3 times with exponential backoff (1s, 2s, 4s).

Common Issues — Server

Server Won't Start: Permission Denied

Symptoms: Server exits immediately with a permission error.

Cause: The server cannot create or write to the data/logs/ directory.

Solution:

1. Check that the data/ directory exists and is writable:

   ls -la data/

2. Fix permissions:

   chmod -R 755 data/

3. If running in Docker, ensure the volume mount has correct ownership

Server Won't Start: Port Already in Use

Symptoms: Server exits with Address already in use error.

Cause: Another process is already using port 50505.

Solution:

1. Find what is using the port:

   lsof -i :50505

2. Stop the conflicting process, or change the Stib port:

   SERVER_PORT=30002 ./stib-server

Server Won't Start: Database Migration Failure

Symptoms: Server exits with a migration error during startup.

Cause: Database schema is corrupted or there is a version mismatch after a downgrade.

Solution:

1. Check the log file for the exact migration error
2. If you downgraded Stib, the database may contain newer schema changes. Restore from a backup taken before the upgrade
3. As a last resort, delete data/stib.db and restart (this loses all data)

DANGER

Deleting the database file removes all projects, cards, agent history, and settings. Always try restoring from a backup first.

Server Won't Start: Startup Hangs

Symptoms: Server appears to start but never becomes responsive.

Cause: The database file may be locked by another process.

Solution:

1. Ensure no other Stib instance is running
2. Check for leftover lock files:

   ls data/stib.db-*

3. If stib.db-wal and stib.db-shm exist but no Stib process is running, it is safe to delete them and restart

High Memory Usage

Symptoms: The Stib server process consumes an unexpectedly large amount of memory over time.

Cause: The in-memory log buffer, active WebSocket connections, or many concurrent agent sessions can increase memory usage.

Solution:

1. Check the number of running agents and cancel any that are no longer needed
2. Reduce the log level to info or warn if set to debug or trace
3. Restart the server to clear the in-memory log buffer (2000 entries)
4. If the issue persists, check for agent processes that did not terminate cleanly:

   ps aux | grep claude

Common Issues — Agents

Agent Fails to Spawn

Symptoms: Card shows an error when trying to start an agent. Error message mentions Claude CLI not found.

Cause: The claude binary is not in the server's PATH.

Solution:

1. Verify Claude Code is installed:

   claude --version

2. If installed but not found, add its location to PATH before starting Stib:

   export PATH="$PATH:/path/to/claude"

3. In Docker, ensure the Claude CLI is available inside the container

Agent Stuck or Unresponsive

Symptoms: Agent appears running but produces no output. The card shows a spinning indicator indefinitely.

Cause: The agent process may be waiting for input or has encountered an unrecoverable state.

Solution:

1. Cancel the agent from the card's overlay panel or action menu
2. Check the agent's conversation for error messages
3. Restart the agent — session history is preserved for context

Context Saturation Relay

Symptoms: Agent output mentions context limits. A new agent session starts automatically.

Cause: The Claude Code agent's context window is full. This is normal behavior — Stib handles it automatically.

Solution:

No action needed. Stib performs an automatic context relay: it spawns a fresh agent and transfers the conversation context. Work continues seamlessly.

INFO

Context relay is a built-in feature. The new agent receives a summary of the previous conversation and continues where the previous agent left off.

Agent Error Message on Card

Symptoms: Card displays a red error badge with an error message.

Cause: The agent process exited with an error. The error is captured and stored on the card.

Solution:

1. Click the card to open the overlay and read the full error message
2. Common causes include:
   • Invalid or expired Claude credentials
   • Network connectivity issues to Anthropic's API
   • File permission issues in the worktree
3. Fix the underlying cause, then retry the agent from the card's action menu

Common Issues — Connection

WebSocket Disconnects

Symptoms: Real-time updates stop. The UI shows a disconnected status. Changes made by other clients are not reflected.

Cause: WebSocket connection dropped due to network issues, proxy timeouts, or server restart.

Solution:

1. Check your network connection
2. If behind a reverse proxy, ensure WebSocket forwarding is configured:

   # Nginx example
   location / {
       proxy_pass http://localhost:50505;
       proxy_http_version 1.1;
       proxy_set_header Upgrade $http_upgrade;
       proxy_set_header Connection "upgrade";
   }

3. Increase proxy timeout values if disconnects happen after inactivity
4. The client reconnects automatically — wait a few seconds

Authentication Errors (401 / 403)

Symptoms: API requests fail with 401 Unauthorized or 403 Forbidden.

Cause: Missing, invalid, or expired authentication token.

Solution:

1. Log out and log back in to refresh your token
2. Check that authentication is properly configured in Settings
3. If using OIDC, verify that your identity provider session has not expired
4. Clear browser cookies and local storage if the issue persists

OIDC Callback Failures

Symptoms: After authenticating with your identity provider, you are redirected back to Stib with an error.

Cause: OIDC configuration mismatch between Stib and the identity provider.

Solution:

1. Verify that the Redirect URI in your identity provider matches Stib's callback URL exactly
2. Check that STIB_SERVER_ORIGIN is set to your public URL
3. Ensure the client ID and client secret are correct in Stib Settings
4. Check the server logs for detailed OIDC error messages

CORS Issues with Reverse Proxy

Symptoms: Browser console shows CORS errors. API requests fail from the frontend.

Cause: Reverse proxy is not forwarding headers correctly, or STIB_SERVER_ORIGIN is misconfigured.

Solution:

1. Set STIB_SERVER_ORIGIN to your public-facing URL (e.g., https://stib.example.com)
2. Ensure your reverse proxy passes through origin headers
3. Do not add extra CORS headers in the proxy — Stib handles CORS internally

Common Issues — Mobile

Mobile App Can't Connect

Symptoms: The mobile app shows a connection error when trying to reach the server.

Cause: The server is not reachable from the mobile device's network.

Solution:

1. Ensure the mobile device and the Stib server are on the same network (or the server is publicly accessible)
2. Use the server's IP address or hostname, not localhost or 127.0.0.1
3. Verify the URL format: http://<server-ip>:50505 (include the port)
4. Check firewall rules — port 50505 must be open for inbound connections
5. Test connectivity from the mobile device:

   http://<server-ip>:50505/api/health

QR Code Scan Failures

Symptoms: The mobile app cannot scan or process the QR code from Settings.

Cause: The QR code encodes the server URL, which may not be reachable from the mobile device.

Solution:

1. Ensure the QR code URL uses an address reachable from the mobile device (not localhost)
2. If using a reverse proxy, verify the STIB_SERVER_ORIGIN is set correctly
3. Try manual connection entry as an alternative

Authentication on Mobile

Symptoms: Login fails on the mobile app despite working in the web UI.

Cause: Authentication token or OIDC flow issues specific to the mobile app.

Solution:

1. For password authentication: verify credentials are correct
2. For OIDC/SSO: ensure the identity provider allows mobile app redirects
3. Check that the server URL is correct and reachable
4. Try logging out and back in

Common Issues — Database

Database Locked

Symptoms: Server logs show "database is locked" errors. Operations fail intermittently.

Cause: Multiple processes are trying to access the SQLite database simultaneously, or a previous process did not shut down cleanly.

Solution:

1. Ensure only one Stib server instance is running
2. Stop the server, delete leftover WAL files if no process is active:

   rm data/stib.db-shm data/stib.db-wal

3. Restart the server

WARNING

Only delete WAL files (stib.db-shm, stib.db-wal) when the server is fully stopped. Deleting them while the server is running can cause data loss.

Migration Errors

Symptoms: Server fails to start with a migration-related error message.

Cause: Database schema version does not match the expected version for the running Stib binary.

Solution:

1. Check the log for the specific migration that failed
2. If you upgraded Stib, the migration should run automatically — check for file permission issues on the database
3. If you downgraded Stib, restore from a backup taken before the upgrade
4. As a last resort, start fresh by removing the database file (data loss)

WAL Mode Issues

Symptoms: Database corruption warnings, unexpected behavior after crash or power loss.

Cause: SQLite WAL (Write-Ahead Logging) files may be incomplete after an unclean shutdown.

Solution:

1. Stop the server
2. Run an integrity check:

   sqlite3 data/stib.db "PRAGMA integrity_check;"

3. If the check reports issues, restore from the most recent backup
4. Restart the server

Environment Variables Reference

Variable	Default	Description
RUST_LOG	stib_server=info,tower_http=info	Log level filter
DATABASE_URL	sqlite://data/stib.db?mode=rwc	SQLite database connection string
SERVER_HOST	0.0.0.0	Address the server binds to
SERVER_PORT	50505	Port the server listens on
CLAUDE_CONFIG_DIR	(Claude CLI default)	Custom directory for Claude OAuth profiles
ANTHROPIC_API_KEY	(none)	API key for Claude (alternative to OAuth credentials)
STIB_SERVER_ORIGIN	(none)	Public URL for CORS and OIDC redirects

Getting Help

Can't resolve your issue? Check the FAQ for answers to common questions, or contact us with your log output and a description of the problem.