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

"No available ports" when starting the server or loading a model¶

Backend.AI GO uses several local TCP port pools:

If a pool is exhausted, the error names the exact host and range, e.g. No available ports for an inference server in 127.0.0.1/0.0.0.0:39000-39019 (tried 20 ports).

• Identify the conflict: Another application may be holding the ports.

  • macOS: lsof -iTCP -sTCP:LISTEN -P
  • Linux: ss -tlnp
  • Windows: netsh int ipv4 show excludedportrange protocol=tcp (run from an elevated prompt — see the next section).

• Change the range: Move the affected pool to a free range in Settings → Advanced → Port Ranges (inference / monitor) or Settings → API → Port (router), then restart the affected service.

• Windows + WSL2 users: Large port ranges may be reserved by the Hyper-V kernel and stay invisible to Resource Monitor. See the dedicated section below.

Windows/WSL2 port conflicts¶

On Windows hosts running WSL2 in Mirrored networking mode, the Hyper-V virtual switch reserves large blocks of TCP ports directly in the Windows kernel when the WSL2 VM boots. These reservations do not appear in Resource Monitor or ordinary netstat/netsh views, so it looks like nothing is using the port — yet continuum-router initialization and model loading fail with "No available ports".

This is a known WSL networking limitation: see microsoft/WSL#40169 and the official WSL networking docs.

Diagnose¶

Run this from an elevated (Administrator) terminal to see the ranges the OS has reserved:

netsh int ipv4 show excludedportrange protocol=tcp

If Backend.AI GO's default ranges (39000–39019, 39080–39090, 39500–39509) fall inside an excluded range, that is the conflict.

Workaround A — Use NAT networking (recommended)¶

Switch WSL2 from Mirrored to NAT networking. NAT mode does not reserve the host's port ranges in the same way, so the conflict disappears. Edit %USERPROFILE%\.wslconfig:

[wsl2]
networkingMode=NAT

Then run wsl --shutdown and restart the WSL2 VM.

Workaround B — Launch order (keep Mirrored networking)¶

If you need Mirrored mode, control the launch order so the VM's local port range is assigned around the ports Backend.AI GO already occupies:

1. Start Backend.AI GO and load your models first.
2. Then start the WSL2 VM.

The Hyper-V reservation is computed relative to the ports already in use at WSL boot, so the order matters. Observed example:

• WSL started first → local port range 36430–40525 (interferes with Backend.AI GO's defaults).
• Backend.AI GO started first → local port range 33700–37795 (no interference).

Caveats¶

• Changing net.ipv4.ip_local_port_range via sysctl inside WSL does not help — it does not propagate back to the Hyper-V reservation made at WSL boot time.
• The [experimental] ignoredPorts setting in .wslconfig works in the opposite direction (it lets Linux reclaim ports that Windows has reserved), so it does not solve this problem.
• As of this writing there is no supported way to manually pin the Hyper-V reserved range, so the NAT switch (Workaround A) or the launch-order trick (Workaround B) are the reliable fixes.

You can also move Backend.AI GO's own pools out of the reserved range in Settings → Advanced → Port Ranges (inference / monitor) and Settings → API → Port (router), then restart the affected service.

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