Troubleshooting

Solutions to common issues when using Rebuttr.

Installation Issues

SQLite compilation errors on install

Cause: Missing build tools required for native module compilation.

Solution: Install platform-specific build tools:

Permission denied errors

Cause: npm global packages require elevated permissions.

Solution: Fix npm permissions or use a node version manager:

Runtime Issues

Port 3001 already in use

Cause: Another process is using port 3001, or a previous Rebuttr instance didn't shut down properly.

Solution:

Browser doesn't open automatically

Cause: The open command isn't available or the browser can't be detected.

Solution: Manually navigate to http://localhost:3001 in your browser.

Changes not saved between sessions

Cause: Database connection issue or file permissions problem.

Solution:

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

   $ ls -la ~/Rebuttr/data/
2. Check the server logs for database errors:
   Terminal

   $ cat /tmp/server.log
3. Try resetting the database (backup first!):
   Terminal

   $ rm ~/Rebuttr/data/review_platform.db

AI features Issues

"OpenCode not ready" error

Cause: OpenCode CLI isn't installed or configured properly.

Solution:

1. Install OpenCode: npm i -g opencode-ai
2. Configure API key: Run opencode and follow the setup prompts
3. Restart Rebuttr

Expert discussions not generating

Cause: AI skills not installed or context not loaded.

Solution:

1. Verify skills are installed:
   Terminal

   $ ls ~/.config/opencode/skill/
2. Reinstall skills:
   Terminal

   $ npm i -g github:genomewalker/rebuttr
3. Click "Update Context" in the AI Knowledge panel

"No draft responses found" when exporting

Cause: Comments don't have responses saved yet.

Solution: You need to either:

• Write manual responses in the Response Builder
• Generate expert discussions and use their recommended responses
• Mark at least some comments as "Completed"

File Processing Issues

PDF not parsing correctly

Cause: PDF has complex formatting, images, or is a scanned document.

Solution:

• Try exporting the PDF as text first
• Use a DOCX file instead if available
• Copy/paste the text directly into Rebuttr

Getting Help

• GitHub Issues: Report a bug
• Debug logs: Run with DEBUG=rebuttr:* rebuttr
• Server logs: Check /tmp/server.log

Reset Everything

If all else fails, you can completely reset Rebuttr: