Troubleshooting

Common issues and how to solve them.

If you need deeper operational guidance, see:

Hook Failures

Hooks Not Firing

If you do not see "Recalletta hook firing" messages at session start or end:

  1. Check status: Run `recalletta hook`. It should show "Enabled: yes" and indicate installations for your clients.
  2. Re-install: Run `recalletta hook enable`.
  3. Verify path: Recalletta skips certain paths by default (e.g., `node_modules`, `.git`). Ensure you are working in a standard project directory.

Session Not Uploading

If sessions do not appear in the dashboard (https://recalletta.ai) or search results:

  1. Check the logs: Inspect `~/.recalletta/log/unified.log` for upload errors.
  2. Verify Auth: Run `recalletta auth` to ensure you are logged in and your API key is valid.
  3. Manual Upload: If a hook failed to upload a specific session, you can manually upload it by prefix: ```bash $ recalletta upload <SESSION_ID_PREFIX> ``` Or upload all unsaved sessions from a provider: ```bash $ recalletta upload claude ```

Crew & Bridge Issues

Crew Command Hangs

If `recalletta crew summon` appears to hang:

  1. Check tmux: Ensure `tmux` is installed and functioning.
  2. Attach to the session: The agent might be waiting for a response or blocked by a tool call. ```bash $ recalletta crew attach <name> ```

Bridge Connectivity

If recalletta crew message fails to reach a remote host:

  1. Ensure the bridge is running: Start it on the target machine (this is safe to run if it's already running). ```bash $ recalletta crew bridge start ```
  2. Verify Port: The default bridge port is 8888. Ensure it is open and not blocked by a firewall.
  3. Direct Test: Try a simple `curl` to the bridge endpoint to verify network visibility.

Knowledge Base Discrepancies

KB Entry Not Injected

If an "important" entry is missing from your agent context:

  1. Verify Pinning: Ensure your directory is pinned to the correct project. Check for a `.recalletta.json` file in your directory or run: ```bash $ recalletta pin <SLUG> ```
  2. Check Importance: Verify the entry or its parent compartment is marked as important in `recalletta kb tree`.
  3. Session Timing: Context is injected only at SessionStart. New KB changes will not appear in a session that is already running.

Local Search Issues

No Results for Local Files

If `recalletta repo search` returns nothing for files you know exist:

  1. Re-index: Your local index might be stale. ```bash $ recalletta repo index ```
  2. Check Status: Run `recalletta repo status` to see when the last index was built and which paths were included.

See Also