Troubleshooting

Harness not found

Symptom: Claude Code not detected or Codex not detected at startup.

Cause: Drisp runs detectVersion() at startup and can't find the harness binary.

Fix:

  • For Claude Code: install and verify with claude --version
  • For Codex: install and verify with codex --version (minimum 0.37.0)
  • Ensure the binary is on your PATH

Socket connection failure

Symptom: Events don't appear in the feed. Hook forwarder exits with connection errors.

Cause: The Unix Domain Socket at <projectDir>/.claude/run/ink-<PID>.sock failed to open or was removed.

Fix:

  • Check if another Drisp instance is running on the same project
  • Verify the .claude/run/ directory exists and is writable
  • Restart Drisp — the socket is created fresh on startup

Hook timeout / auto-passthrough

Symptom: Tool calls proceed without Drisp evaluating them. Feed shows events arriving late.

Cause: The hook forwarder has a 5-second auto-passthrough timeout. If Drisp can't respond in time, the forwarder exits with code 0 (allow). Permission and question events have a 5-minute timeout.

Fix:

  • Check system load — SQLite writes and policy evaluation should be sub-millisecond
  • If running in degraded mode (SQLite unavailable), the bottleneck may be the fallback in-memory store

Session corruption / can't resume

Symptom: drisp resume fails or shows incomplete data.

Cause: The SQLite database at ~/.config/drisp/sessions/<uuid>/session.db may be corrupted (disk full during write, forced kill).

Fix:

  • Try opening the database with sqlite3 to check: sqlite3 ~/.config/drisp/sessions/<uuid>/session.db ".tables"
  • If corrupted, delete the session directory — that session's history is lost but Drisp will work normally for new sessions

Plugin loading errors

Symptom: Plugin not found or Missing plugin.json errors at startup.

Cause: The plugin path doesn't point to a valid plugin directory (missing .claude-plugin/plugin.json).

Fix:

  • Verify the path: ls <plugin-path>/.claude-plugin/plugin.json
  • For marketplace refs, check that the marketplace repo is accessible: ls ~/.config/drisp/marketplaces/<owner>/<repo>/
  • If offline, Drisp uses the cached marketplace. If no cache exists, the plugin can't be resolved

MCP server name collision

Symptom: MCP server name collision: "my-server" is defined by multiple plugins.

Cause: Two loaded plugins define MCP servers with the same name.

Fix: Rename one of the MCP servers in its plugin's .mcp.json file. Names must be unique across all loaded plugins.

Degraded mode

Symptom: Header shows degraded state indicator. Sessions can't be resumed.

Cause: SQLite database can't be opened (disk full, permissions, locked by another process).

Fix:

  • Check disk space: df -h
  • Check permissions on ~/.config/drisp/sessions/
  • If another Drisp instance holds a WAL lock, close it first

Workflow not found

Symptom: Workflow "my-workflow" not found in local registry.

Cause: The workflow hasn't been installed. --workflow looks up ~/.config/drisp/workflows/<name>/workflow.json.

Fix:

drisp workflow install my-workflow@owner/repo --name my-workflow

Debug logging

Set DRISP_DEBUG=1 to enable verbose debug output from hook registration and the socket server:

DRISP_DEBUG=1 drisp