Common Issues

Solutions for frequently encountered problems with Bitloops.

Session Appears Stuck

Symptom: bitloops status shows an active session that should have ended.

Solution: Run the doctor command to diagnose:

bitloops doctor

If the session is genuinely stuck, reset the state:

bitloops reset

This clears the shadow state without deleting checkpoint data.

Symptom: You're using an AI agent but bitloops status shows no session activity.

Possible causes:

Bitloops not enabled — run bitloops enable
Hooks not installed — reinitialize: bitloops init --agent <name> --force
Agent not detected — specify the agent explicitly: bitloops init --agent claude-code

Symptom: bitloops devql ingest errors out.

Steps:

Check store connectivity:
```
bitloops --connection-status
```
Re-initialize the schema:
```
bitloops devql init
```
If using PostgreSQL or ClickHouse, verify the connection string in .bitloops/config.json

Symptom: bitloops dashboard fails or the page doesn't load.

Possible causes:

Port already in use — try a different port:
```
bitloops dashboard --port 8080
```
Stores not initialized — run bitloops devql init first
Check for errors in the terminal output when starting the dashboard

Symptom: You committed code from an AI session but no checkpoint was created.

Check:

Symptom: Storage grows unexpectedly or data seems inconsistent.

Solution: Clean up orphaned data:

bitloops clean

This removes data that's no longer linked to valid sessions or checkpoints.

If these solutions don't resolve your issue: