Troubleshooting Guide

This guide provides direct, practical fixes for common issues encountered during runtime initialization, model loading, and API interaction.

1. CUDA Out of Memory (OOM)

Likely Cause: The model parameter count combined with full-precision weights exceeds the physical VRAM of your GPU (e.g. attempting to load a 14B model on a free 15 GB Colab T4 GPU).

Practical Fix:

1. Switch precision from float32 to float16 or bfloat16, which cuts memory consumption in half.
2. Choose a smaller model preset (e.g. Qwen/Qwen2.5-0.5B requiring ~1.2 GB, or Qwen/Qwen2.5-1.5B requiring ~3.5 GB).
3. In Advanced Settings, reduce Max Tokens from 2048 to 512 or 256.

2. Model Download or Gated Access Error

Likely Cause: The model (e.g. Meta LLaMA 3.2) requires explicit agreement to its license on Hugging Face, or your Hugging Face token is missing/expired.

Practical Fix:

1. Log into huggingface.co and visit the model repository page to accept the terms.
2. Create a read token under Settings → Access Tokens.
3. Paste the token into the HF Token field in Section 1 of the notebook.

3. Cloudflare Tunnel Initialization Timeout

Likely Cause: Transient edge routing latency or DNS throttling on the Cloudflare Quick Tunnel network.

Practical Fix:

1. Click START APEX again. Quick Tunnels often resolve successfully on a second connection attempt.
2. If developing on a local workstation, open Advanced Settings and set Transport to Local Port Only.

4. Authentication & 401 Unauthorized Errors

Likely Cause: The client is omitting the Authorization: Bearer <key> header, or using an incorrect key.

Practical Fix:

1. In Section 1, locate the Active API Key container in the Connection Panel.
2. Click the reveal toggle to view the real active key and copy it into your client configuration.
3. If you do not require token security, uncheck Enable Bearer Authentication in Advanced Settings and click START APEX.

5. Google Colab Session Disconnect

Likely Cause: Google Colab free tier instances disconnect automatically after periods of user inactivity or after reaching the maximum 12-hour session limit.

Practical Fix:

1. In the Colab toolbar, click Reconnect.
2. Ensure GPU acceleration remains selected: Runtime → Change runtime type → T4 GPU.
3. Re-run Section 1 and click START APEX to re-initialize your model.

6. Port Conflict (Address Already in Use)

Likely Cause: A dangling process from a previously interrupted Python session is still bound to port 8000.

Practical Fix:

APEX includes automatic port search logic and will scan up to 10 consecutive ports (e.g. 8001, 8002). You can also explicitly specify an alternate port (such as 8080) in Advanced Settings.