This page covers common issues and how to resolve them. If your problem is not listed here, search the documentation or reach out on the community Discord.
Problem: "Backend not reachable" when starting a session
The ACP server subprocess failed to start or exited. Verify the command + args entry in acp.json runs successfully when you invoke it directly in a shell, confirm any required environment variables are set in the env block, and check that no required runtime (Node, Python, Ollama) is missing. Run /status in the TUI to check connection status.
Problem: "Protocol handshake failed"
The backend does not support ACP v1, or the endpoint is not an ACP server. Confirm the backend implements ACP protocol version 1 and is configured to accept connections. Some backends require enabling ACP support explicitly.
Problem: "Authentication failed"
Your API key or credentials are expired or incorrect. Update them by editing the relevant variable inside the env block of the backend's entry in acp.json (for example, ANTHROPIC_API_KEY, OPENAI_API_KEY) and restarting simse. Some backends rotate keys periodically — check the provider's dashboard for your current key.
Problem: "MCP server not reachable"
The MCP server process failed to start. mcp.json entries configure stdio subprocesses — confirm the command + args entry runs successfully when you invoke it directly, and that any vars in requiredEnv are set. Run simse mcp status to check tool server status.
Problem: Tools appear in the registry but do not respond
The MCP server may have started but is not processing requests. Check the server logs for errors. Restart MCP servers with simse mcp restart or /mcp restart from the TUI.
Problem: "Protocol error" when using a tool
The MCP server version may be incompatible. Verify the server implements the MCP specification that simse expects. Update the server if a newer version is available.
Problem: Search returns no results for content you know exists
The content may not be indexed yet. Indexing happens asynchronously after sessions end. Wait a few seconds and search again. If the problem persists, ask simse to compact the relevant topic using library_compact, which rebuilds entries within that topic.
Problem: "Storage limit reached"
The adaptive store has reached its size limit. Use library_withdraw to remove specific entries by ID to free space.
Problem: Adaptive store takes a long time to load
Large stores with many entries take longer to load from disk. Enable binary quantization to reduce the stored size, or increase the available memory. The store loads once at startup and stays in memory.
Problem: Shell commands time out
The default command timeout may be too short for long-running operations. Increase the timeout in sandbox configuration. If a command hangs indefinitely, it may be waiting for input that the sandbox cannot provide.
Problem: "Permission denied" when accessing files in the sandbox
The sandbox respects host filesystem permissions. Verify the simse process has read/write access to the target directory.
Problem: SSH connection fails
Check that the SSH host is reachable, the credentials are correct, and the SSH service is running on the remote host. Verify your SSH key is configured in the sandbox settings.
Problem: Context from a previous session does not appear
Context surfaces based on relevance to the current session. If the previous session's content is not relevant to what you are working on now, it may not appear automatically. Ask simse to search the library for specific entries — it uses library_search to find them.
Problem: "Session not found" when resuming
The session data may have been deleted or moved. List available sessions by running the simse resume CLI subcommand with no ID. If the session is missing, its context is still in the adaptive store and will surface in future sessions when relevant.
Problem: Binary does not start on macOS
macOS may quarantine downloaded binaries. Remove the quarantine attribute:
xattr -d com.apple.quarantine ./simseProblem: Binary does not start on Linux
Ensure the binary has execute permission:
chmod +x ./simseIf the binary reports missing shared libraries, you may need to install system dependencies. The release binary is statically linked where possible, but some features may require runtime libraries.