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

"App from an Unidentified Developer" warning (macOS)¶

macOS Gatekeeper may block the app if it was downloaded outside the Mac App Store, showing a message that the developer cannot be verified.

1. Go to Apple menu () > System Settings > Privacy & Security.
2. Scroll down to the Security section. You will see a message about the blocked app.
3. Click "Open Anyway".
4. Enter your login password and confirm.

For more details, see Apple's official guidance: https://support.apple.com/guide/mac-help/mchleab3a043/mac

"Windows protected your PC" (SmartScreen)¶

Windows SmartScreen blocks apps from publishers who have not yet accumulated a reputation score with Microsoft.

1. In the SmartScreen dialog, click "More info".
2. Click "Run anyway" to proceed.

Antivirus Removes or Quarantines Files After Installation (Windows)¶

Some antivirus software incorrectly flags the inference engine binary (llama-server-x86_64-pc-windows-msvc.exe) as malware. This is a known false positive.

Resolution steps:

1. Open your antivirus dashboard and navigate to the quarantine or threat history section.
2. Restore the quarantined file if available.
3. Add the following paths as exclusions/exceptions in your antivirus settings:
   • %LOCALAPPDATA%\Programs\backend.ai.go\
   • %LOCALAPPDATA%\backend.ai.go\engines\
   • %APPDATA%\backend.ai.go\
4. Reinstall Backend.AI GO from the official release after adding the exclusions.

Missing Visual C++ Runtime (Windows)¶

If the application fails to start with an error such as VCRUNTIME140.dll not found or MSVCP140.dll not found, the Microsoft Visual C++ Redistributable is missing or outdated.

Resolution:

Download and install the latest Visual C++ Redistributable (x64) from the Microsoft Download Center.

After installation, restart your computer and try launching Backend.AI GO again.

CUDA Driver Requirements for GPU Acceleration (Windows)¶

Backend.AI GO requires CUDA 12.x for NVIDIA GPU acceleration on Windows.

1. Open a Command Prompt and run nvidia-smi. If this command fails, your driver is outdated or not installed.
2. Download the latest Game Ready or Studio driver from nvidia.com/drivers.
3. After installing the driver, restart your computer.
4. In Backend.AI GO, go to Settings > Engines and select a CUDA-enabled engine if not already selected.

AppImage Does Not Execute (Linux)¶

If double-clicking the AppImage does nothing, or running it from a terminal shows a permission error:

Step 1 — Add execute permission:

chmod +x Backend.AI-GO.AppImage
./Backend.AI-GO.AppImage

Step 2 — Install FUSE (if the app still does not run):

AppImages require FUSE 2 on most Linux distributions.

# Ubuntu 22.04 and later / Debian
sudo apt update && sudo apt install libfuse2

# Ubuntu 24.04 (noble) — FUSE 2 is in universe
sudo apt update && sudo apt install libfuse2t64

# Fedora
sudo dnf install fuse

# Arch Linux
sudo pacman -S fuse2

After installing FUSE, run the AppImage again.

Missing Shared Libraries (Linux)¶

If Backend.AI GO fails to start with errors like libwebkit2gtk-4.1.so.0: cannot open shared object file, install the required dependencies:

# Ubuntu / Debian
sudo apt update
sudo apt install libwebkit2gtk-4.1-0 libgtk-3-0 libayatana-appindicator3-1

# Fedora
sudo dnf install webkit2gtk4.1 gtk3 libayatana-appindicator

# Arch Linux
sudo pacman -S webkit2gtk-4.1 gtk3

GPU Driver Setup for Linux¶

NVIDIA CUDA:

1. Verify that the driver is loaded: nvidia-smi

2. If the command is not found, install the driver from your distribution's package manager or from nvidia.com/drivers.

   # Ubuntu
   sudo apt install nvidia-driver-570
   

3. Verify CUDA is available after reboot: nvidia-smi should show the CUDA version.

AMD ROCm:

1. Follow the official ROCm installation guide at rocm.docs.amd.com.

2. Add your user to the render and video groups:

   sudo usermod -aG render,video $USER
   

3. Log out and back in, then verify with rocminfo.

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

UI layout appears broken or behaves unexpectedly¶

• Reset UI State: If sidebar positions, tab selections, or scroll positions seem corrupted, you can reset all UI preferences:
  1. Navigate to Settings > UI
  2. Find the UI State section
  3. Click Reset UI State to restore default layout

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

"Binary not found" or "Inference Engine Not Found" (Windows)¶

This error occurs when the inference engine (llama-server) cannot be located. This can happen due to:

• Antivirus Interference: Some antivirus software may quarantine or delete the llama-server-x86_64-pc-windows-msvc.exe binary, mistaking it for a threat.

  • Solution: Add an exception for the Backend.AI GO installation directory in your antivirus settings.
  • Common paths to whitelist:
    • %LOCALAPPDATA%\Programs\backend.ai.go\
    • %LOCALAPPDATA%\backend.ai.go\engines\
    • %APPDATA%\backend.ai.go\

• Incomplete Installation: The installation might have been interrupted.

  • Solution: Reinstall Backend.AI GO from the official release.

• Missing Engine: The bundled engine might not be present. Backend.AI GO now supports downloadable engines.

  • Solution: Navigate to Settings > Engines and download a compatible inference engine for your system.

• File Permission Issues: Windows security policies might prevent access to the binary.

  • Solution: Try running the application as Administrator once, or check folder permissions.

Troubleshooting Steps:

1. Check the notification center for an "Inference Engine Not Found" message
2. Click "Download Engine" to navigate to the Engines page
3. Download a compatible engine (e.g., llama-cpp with CUDA or CPU support)
4. Retry loading your model

Debug Information: The error message will show the expected binary name and searched paths to help identify where the engine should be located.

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

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.

Multi-part model shows "Incomplete" badge¶

Large models (70B+ parameters) are often split into multiple files (e.g., model.gguf-00001-of-00006.gguf). If you see an "Incomplete" warning badge on a model card:

• Check Missing Parts: Hover over the badge to see which parts are missing (e.g., "Missing parts: 2, 3, 5 of 6").

• Resume Download: Go to the Downloads tab and resume any paused or failed downloads for the missing parts.

• Manual Download: If the download was interrupted, you may need to re-download the missing parts from Hugging Face.

• File Verification: Ensure all part files are in the same directory and follow the naming pattern model.gguf-NNNNN-of-NNNNN.gguf.

• Cannot Load: Incomplete multi-part models cannot be loaded until all parts are present. The Load button will be disabled.

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

Viewing Provider Connection Errors¶

If a cloud provider fails to connect or returns errors, you can view detailed error logs in the Logs panel:

1. Open the Logs panel from the sidebar
2. Filter by API source to see provider-related messages
3. Look for error entries that include:
   • Connection failures (timeout, unreachable host)
   • Authentication errors (401, 403)
   • Rate limiting (429)
   • Server errors (5xx)

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

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