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 (like GPT-5.1) 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: 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).

"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: Screen recording permissions might be denied (common on macOS, rare on Windows).
  • Fix: Run Rephlo as Administrator or check Windows Privacy settings.

"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.

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 "Don't Save", 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 (Claude Sonnet 4.5 200K, Gemini 3 2M+).

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.