🏥 Common Issues & Troubleshooting

If you encounter problems with HelseCLI, check this guide first for common solutions.

🔑 Authentication & API Issues

Issue: "Authentication Error" or "401 Unauthorized"

• Cause: Invalid or expired API key.
• Solution: Verify your .env keys. Ensure they don't have extra spaces or quotes around them.
• Check: Run python helsecli.py version to see which keys are detected.

Issue: "Rate Limit Exceeded"

• Cause: You've hit the usage limit for your LLM provider (OpenAI/Anthropic).
• Solution: Wait for the cooldown period or upgrade your API tier. You can also switch to a different provider using !m.

🐳 Sandbox & Execution Issues

Issue: "Docker not found or daemon not running"

• Solution: Ensure Docker Desktop is open and the status is "Running". On Linux, ensure your user is in the docker group.

Issue: "ModuleNotFoundError" inside the sandbox

• Cause: The code requires a library that isn't installed in the sandbox.
• Solution:
  1. Tell the AI: "Install [package] using pip and try again."
  2. Or, add the package to your requirements.txt and the sandbox will auto-install it on the next run.

Issue: "Timeout Error"

• Cause: A script or shell command took too long to respond.
• Solution: Increase the HELSE_COMMAND_TIMEOUT in your config or .env (default is 60 seconds).

📄 Document Generation Issues

Issue: "Pandoc not found"

• Cause: You're trying to export to PDF or DOCX without Pandoc installed.
• Solution: Install Pandoc from pandoc.org.

Issue: "Empty Document Generated"

• Cause: Usually occurs if the AI plan was too complex or the research phase failed.
• Solution: Try a simpler objective first, or disable Web Research to see if that's the blocker.

⌨️ Interface & UI Issues

Issue: "Garbled Text or Weird Characters"

• Cause: Your terminal doesn't support ANSI colors or Unicode properly.
• Solution: Use a modern terminal like Windows Terminal, iTerm2, or VS Code's integrated terminal. Set HELSE_NO_COLOR=1 in .env if the problem persists.

Issue: "Keyboard Shortcuts not working"

• Cause: Some terminals intercept Ctrl combinations.
• Solution: Check your terminal's "Hotkeys" or "Keyboard" settings and ensure they aren't overriding HelseCLI shortcuts.

🐛 Generating a Debug Log

If your issue isn't listed here, help us help you by generating a debug log:

1. Run HelseCLI with debug mode: HELSE_DEBUG=1 python helsecli.py code
2. Reproduce the error.
3. Check the logs/helsecli.log file for detailed error messages.
4. Open an issue on GitHub with this log attached.