Troubleshooting Guide¶

This comprehensive guide addresses common issues you might encounter while using Backend.AI GO.

1. Installation & Startup¶

App does not open (No response)¶

Check Processes: Sometimes a background process from a previous session might be stuck. Open Task Manager (Windows) or Activity Monitor (macOS) and kill any backend-ai-go or llama-server processes.
Reinstall: The installation might be corrupted. Reinstall the latest version.

"App is damaged and can't be opened" (macOS)¶

This is a common macOS security message for apps not downloaded from the App Store.

Solution: Right-click the app icon and select Open. Click Open again in the dialog box.
Terminal Fix: If that fails, run this command in Terminal:
```
xattr -cr /Applications/Backend.AI\ GO.app
```

"Windows protected your PC" (SmartScreen)¶

Solution: Click More info, then click the Run anyway button.

App crashes immediately on launch¶

Config Reset: Your configuration file might be corrupted. Try renaming or deleting the config folder:
- Windows: %APPDATA%\backend.ai.go
- macOS: ~/Library/Application Support/backend.ai.go
- Linux: ~/.config/backend.ai.go

"Port 8000/8001 is already in use"¶

Backend.AI GO uses port 8000 for the API server and 8001 for management.

Identify Conflict: Another app (like a local web server or another AI tool) might be using these ports.
Change Port: (Future feature) Currently, you must stop the conflicting application.

2. Model Download & Management¶

Download stuck at 0%¶

Firewall: Check if your firewall or antivirus is blocking the connection to Hugging Face.
Proxy: If you are behind a corporate proxy, ensure HTTP_PROXY and HTTPS_PROXY env vars are set correctly.

"Download Failed (Network Error)"¶

Resume: Click the retry button. The download supports resuming.
Disk Space: Verify you have enough space. A "Network Error" can sometimes mask a "Disk Full" error.

Slow Download Speed¶

Hugging Face Mirror: In some regions, the connection to Hugging Face might be slow.
External Download: You can download the .gguf file using a browser or download manager, then use the Import feature.

Model not showing in Library¶

Refresh: Click the refresh icon in the library header.
File Extension: Ensure the file ends in .gguf.
Location: Verify the file is in the correct models directory (visible in Settings).

Cannot delete model (File Locked)¶

Unload First: Ensure the model is not currently loaded.
Restart App: Fully quit Backend.AI GO to release any file locks.

3. Loading & Inference¶

App freezes during loading¶

Large Model: Loading a Solar-Open-100B or gpt-oss-120B model into RAM can take time. Wait for 2-3 minutes.
System RAM: If your system runs out of RAM, the OS will start swapping, which causes extreme slowdowns. Ensure you are not loading a model larger than your physical RAM.

"Out of Memory (OOM)" Error¶

Reduce Context: Lower the Context Length in Model Settings (e.g., from 8192 to 4096).
More GPU Offloading: If using CPU+GPU, try offloading fewer layers to GPU if VRAM is the bottleneck, or more if system RAM is the bottleneck.
Smaller Quantization: Switch from Q8_0 to Q4_K_M.

Using CPU instead of GPU¶

Check Settings: In Model Settings, ensure GPU Layers is not set to 0. Set it to Max or -1.
Drivers:
- Windows: Install the latest NVIDIA Studio or Game Ready drivers.
- Linux: Ensure CUDA toolkit is installed and nvidia-smi works.

MLX model fails to load (macOS)¶

Chip Compatibility: MLX requires Apple Silicon (M1/M2/M3/M4/M5). It does not work on Intel Macs.
OS Version: Ensure you are on macOS 13.0 (Ventura) or later.

Model outputs gibberish¶

Repetition Penalty: If it repeats words, increase Frequency Penalty.
Temperature: If it speaks nonsense, lower Temperature (e.g., to 0.7).
Template: The internal prompt template might be mismatched. Try manually selecting the correct template (ChatML, Llama 3, etc.) in settings.

Slow generation speed (Low TPS)¶

Power Mode: Ensure your laptop is plugged in.
Background Apps: Close web browsers or Electron apps (Slack, Discord) to free up memory bandwidth.

4. Chat & Features¶

Enter key does not send message¶

Loading State: Check if the model is still loading or generating a response.
Generation: You cannot send a message while the AI is typing. Click Stop first.

Missing chat history¶

Database: Chat history is stored locally. If you cleared your app data or reinstalled cleanly, history might be gone.
Search: Use the search bar in the sidebar; the chat might just be scrolled out of view.

Image attachment fails¶

Model Support: Ensure you are using a Multimodal model (e.g., Llama-3.2-Vision, Qwen2-VL). Standard text models cannot "see" images.

"Thinking Block" not visible¶

Model Support: Only reasoning models (DeepSeek-R1, Qwen3-Thinking) output thinking traces. Standard models will just give the answer directly.

Tool calling errors¶

Model Capability: Ensure the model supports tool calling. Small models (< 7B) often struggle with tool formatting.
Permission: Did you deny the permission request? Check the chat for a permission prompt.

Answering in English instead of User Language¶

System Prompt: Add a system prompt: "You are a helpful assistant. Always answer in the user's language."
Model Bias: Some smaller models are heavily English-biased. Try a larger model or one fine-tuned for your language.

5. Cloud Integration¶

"Invalid Key" error¶

Whitespace: Check for hidden spaces at the start or end of your API key.
Quota: Check if you have run out of credits/quota on the provider's platform (OpenAI, Anthropic).

Cloud models not listed¶

Refresh: It might take a moment to fetch the list.
Key Permissions: Ensure your API key has permissions to list models.

Remote vLLM connection failed¶

Network: Can you ping the server IP?
Firewall: Ensure port 8000 is open on the remote server.
CORS: If running vLLM, ensure you launched it with --cors-allow-origins "*".

6. macOS Specific Issues¶

"System Not Supported" on macOS¶

Intel Macs: Backend.AI GO requires Apple Silicon (M1/M2/M3/M4/M5). Intel-based Macs are not supported. If you need to run AI on an Intel Mac, consider using the Cloud Integration features.

For general questions about features or usage, please visit the FAQ page.

Still stuck? Join our Discord community or open an issue on GitHub.