Skip to main content

Troubleshooting

Common issues and how to fix them.

Provider Issues​

"Error: 401 Unauthorized"​

  • Cause: Invalid API Key.
  • Fix: Go to Settings > Providers. Re-enter your API Key. Ensure there are no extra spaces or line breaks.

"Error: 403 Forbidden"​

  • Cause: Your API key doesn't have access to the requested model.
  • Fix:
    • For OpenAI: Some models require a paid tier. Check your access at platform.openai.com.
    • For Anthropic: Ensure your account has access to the Claude model you're requesting.

"Error: 429 Too Many Requests"​

  • Cause: You've hit the rate limit or run out of credits.
  • Fix:
    • Wait a few minutes and try again (rate limit).
    • Check your billing status and add credits at the provider's website.
    • Consider switching to a different provider temporarily.

"Error: 500 Internal Server Error"​

  • Cause: The provider's servers are experiencing issues.
  • Fix: Wait a few minutes and retry. Check the provider's status page.

"Connection Refused" (Ollama)​

  • Cause: Rephlo cannot talk to the local AI server.
  • Fix:
    1. Open a terminal and run ollama serve.
    2. Verify it's running: visit http://localhost:11434 in a browser.
    3. Check if another application is using port 11434.

"Model Not Found" (Ollama)​

  • Cause: The requested model isn't downloaded.
  • Fix: Run ollama pull [model-name] in your terminal (e.g., ollama pull llama3).

UI Issues​

"Hotkeys are not working"​

  • Cause (Windows/Linux): Another application (like PowerToys or a game) might have stolen the hotkey.
  • Fix: Go to Settings > Hotkeys and change the trigger to something else (e.g., Ctrl + Shift + Alt + Z).

macOS users: See macOS-Specific Issues below for hotkey troubleshooting on macOS.

"Tray Icon is Missing"​

  • Cause: Windows might have hidden it in the "overflow" menu.
  • Fix: Click the ^ arrow near the clock. Drag the Rephlo icon out to the main taskbar area.

Feature Issues​

"Vision/Screenshot not working"​

  • Cause (Windows): Screen recording permissions might be denied in Windows Privacy settings.
  • Fix (Windows): Run Rephlo as Administrator or check Windows Privacy settings > Camera / Screen capture.
  • Cause (macOS): Rephlo requires Screen Recording permission.
  • Fix (macOS): See macOS-Specific Issues below for detailed steps.

"Space is not answering questions"​

  • Cause: The space might be empty or ingestion failed.
  • Fix: Check the Space details. Ensure files are listed and status says "Ready". Try clearing the cache in Advanced Settings.

"Variable not found in Space"​

  • Cause: You're using a {{filename}} variable but the file isn't in the active Space.
  • Fix:
    1. Check the Space contains the referenced file.
    2. Verify the variable name matches the file name (converted to snake_case, e.g., "Style Guide.pdf" -> {{style_guide_pdf}}).
    3. Ensure the correct Space is active.

macOS-Specific Issues​

"Hotkeys are not working" (macOS)​

  • Cause: Rephlo requires Accessibility permission to monitor keyboard events via CGEventTap.
  • Fix:
    1. Open System Settings > Privacy & Security > Accessibility.
    2. Find Rephlo in the list and toggle it ON.
    3. If Rephlo isn't listed, quit and relaunch the app.
    4. Restart Rephlo after granting permission.

Important: Global hotkeys only work when running Rephlo as a signed .app bundle. If you are a developer running dotnet run from terminal, hotkeys may not function. See the macOS Setup Tutorial for building and running the .app bundle.

"Screenshot / Vision not working" (macOS)​

  • Cause: Rephlo requires Screen Recording permission to capture screen content.
  • Fix:
    1. Open System Settings > Privacy & Security > Screen Recording.
    2. Find Rephlo in the list and toggle it ON.
    3. Restart Rephlo.

"Permission dialog keeps appearing"​

  • Cause: Rephlo was running without a stable code signature. Each rebuild changes the binary hash, causing macOS to treat it as a new app and reset permissions.
  • Fix: Use a signed release build of Rephlo from the official distribution. After granting permissions once to the signed app, they persist across updates.

"Overlay doesn't appear even after granting permissions"​

  • Fix:
    1. Quit Rephlo completely (right-click tray icon > Exit).
    2. Relaunch from the .app bundle.
    3. Check both Accessibility AND Screen Recording permissions are granted.
    4. Try the Test Overlay button in Settings > Hotkeys.

Performance Issues​

"Responses are very slow"​

  • Cause: Various factors can slow down responses.
  • Fix:
    • Large Space context: Consider compacting your Space.
    • Slow provider: Try Groq for faster responses.
    • Local model (Ollama): Ensure your GPU is being utilized. Check Ollama logs.

"App feels sluggish on startup"​

  • Cause: Loading large Spaces or many commands.
  • Fix: Archive unused commands. Remove old Spaces you no longer need.

Chat Issues​

"Chat history is missing"​

  • Cause: Conversations are stored locally and may have been cleared.
  • Fix: Check Settings > Privacy for history retention settings. If set to "Immediate", history is not preserved.

"Chat keeps forgetting context"​

  • Cause: You've exceeded the provider's context window.
  • Fix: Start a new conversation or use a provider with a larger context window. Check your provider's documentation for specific context window sizes.

Variable & Template Issues​

"Variable not found" or "Invalid variable"​

  • Cause: The variable name doesn't match a valid system variable or file in your Space.
  • Fix:
    • Use exact syntax: {{input_text}}, {{space_data_all}}, or {{filename}}.
    • For file variables: Convert file name to snake_case (e.g., "Style Guide.pdf" -> {{style_guide_pdf}}).
    • Verify the file exists in your active Space.
    • Check for typos--variable names are case-insensitive but must be spelled correctly.

"Space variables ignored in Standalone mode"​

  • Cause: Standalone commands don't auto-inject Space data.
  • Explanation: Standalone mode gives you full manual control. Variables like {{space_data_all}} won't be replaced automatically.
  • Fix: Switch to Combination mode for automatic Space data injection, or manually paste the Space data into your prompt.

Space Issues​

"Space full" or "Token budget exceeded"​

  • Cause: Your Space has exceeded its configured token limit.
  • Fix:
    1. Open Space settings and review current usage.
    2. Enable Smart Compaction (Settings > Spaces > Compaction Strategy).
    3. Choose a compaction level:
      • Conservative: Minimal summarization (preserves detail).
      • Balanced: Moderate summarization (default, recommended).
      • Aggressive: Heavy summarization (best for very large Spaces).
    4. Alternatively, increase the token budget (max 1,000,000 tokens).
    5. Or remove less important files from the Space.

"Space ingestion failed" (PDF/document error)​

  • Cause: The file couldn't be processed--possibly corrupted, password-protected, or in an unsupported format.
  • Fix:
    • Ensure PDF isn't password-protected.
    • Try re-exporting the document from the source application.
    • For scanned PDFs: Rephlo extracts text only--images inside PDFs are not read.
    • Check file isn't corrupted by opening in another application first.