CDN_DIAGNOSTICS.md

# WebLLM CDN Diagnostics & Troubleshooting

## Issue: "WebLLM library is still loading from CDN. Please wait..."

This message appears when the CDN takes longer than expected to load. This guide helps you troubleshoot.

---

## Quick Diagnostic (Copy-Paste to Console)

Open https://snapkittywest.github.io/rowm-polymorphic-notebook/index-app.html, press F12, then paste:

```javascript

// Check CDN loading status

console.log('=== WebLLM CDN Status ===');

console.log('Ready:', window.webllmReady);

console.log('Loading:', window.webllmCDNLoading);

console.log('Error:', window.webllmError);

console.log('Library type:', typeof window.webllm);

console.log('Load time (ms):', window.webllmLoadTimestamp ? Date.now() - window.webllmLoadTimestamp : 'N/A');



// If loaded, show MLCEngine

if (window.webllm && window.webllm.MLCEngine) {

    console.log('MLCEngine available:', typeof window.webllm.MLCEngine);

} else if (window.webllm) {

    console.log('WebLLM loaded but MLCEngine not found');

} else {

    console.log('WebLLM not loaded yet');

}

```

**Expected Output (Success):**
```

Ready: true

Loading: false

Error: null

Library type: object

Load time: 2500 (milliseconds)

MLCEngine available: function

```

**Expected Output (Slow Loading):**
```

Ready: false

Loading: true

Error: null

Library type: undefined

Load time: 8500

MLCEngine available: N/A

```

---

## Network Tab Analysis

1. Open DevTools > Network tab
2. Reload page (F5)
3. Look for: `web-llm.js` request

**Check the following:**

| Item | Good | Bad | Fix |
|------|------|-----|-----|
| **Status** | 200, 304 | 404, 403, 0 | Check CDN URL or internet |
| **Time** | <5s | >10s | CDN slow, try unpkg fallback |
| **Size** | 1.5MB | Much larger | File corrupted, retry |
| **CORS** | No error | CORS error | Network/firewall blocking |

**CDN URLs Used (in order):**
1. Primary: `https://cdn.jsdelivr.net/npm/@mlc-ai/web-llm@0.2.32/dist/web-llm.js`
2. Fallback: `https://unpkg.com/@mlc-ai/web-llm@0.2.32/dist/web-llm.js`

---

## Common Issues & Solutions

### Issue 1: CDN Loads But Takes 10+ Seconds

**Symptoms:**
- Console shows: `Ready: false`, `Loading: true` for >10 seconds
- Network tab shows: Status 200 but very slow transfer

**Causes:**
- Slow internet connection
- CDN server responding slowly
- Large file size (1.5MB)

**Solutions:**
```javascript

// Option A: Force retry from backup CDN

window.retryWebLLMLoad();



// Option B: Wait longer (CDN may still load)

// Just wait 30 more seconds, then try LOAD LOCAL MODEL again

```

### Issue 2: CDN Request Times Out (No Response)

**Symptoms:**
- Console shows: `Error: jsDelivr timeout`
- Network tab shows: CDN request pending indefinitely or canceled

**Causes:**
- Network timeout (CDN unreachable)
- Firewall/proxy blocking CDN
- ISP throttling or filtering

**Solutions:**
```javascript

// Automatic: Fallback to unpkg triggers after 8 seconds

// Manual retry:

window.retryWebLLMLoad();



// If still fails, try from corporate WiFi or personal hotspot

```

### Issue 3: CORS Error

**Symptoms:**
- Console shows: `Access to XMLHttpRequest from 'file://...' has been blocked by CORS policy`
- Or: `Access to fetch from 'https://cdn.jsdelivr.net' blocked by CORS`

**Causes:**
- Opening file:// directly (not via HTTP server)
- Corporate proxy filtering cross-origin requests

**Solutions:**
```javascript

// Must use HTTP/HTTPS, not file://

// Visit: https://snapkittywest.github.io/rowm-polymorphic-notebook/index-app.html

// NOT: file:///C:/Users/.../index-app.html



// If corporate network:

// 1. Ask IT to whitelist: cdn.jsdelivr.net

// 2. Try from personal WiFi/hotspot

// 3. Use VPN if allowed

```

### Issue 4: WebLLM Loads But window.webllm Is undefined

**Symptoms:**
- Network tab shows: 200 (file downloaded)
- Console shows: `typeof window.webllm: undefined`

**Causes:**
- Script loaded but didn't execute properly
- File corrupted or wrong version
- Browser doesn't support WASM or async

**Solutions:**
```javascript

// Manually retry:

window.retryWebLLMLoad();



// Check browser compatibility:

console.log('WebAssembly:', typeof WebAssembly !== 'undefined');

console.log('Promise:', typeof Promise !== 'undefined');

console.log('Symbol.asyncIterator:', Symbol.asyncIterator);

```

### Issue 5: "Please Wait..." Message Never Disappears

**Symptoms:**
- Message: "WebLLM library is still loading from CDN. Please wait..."
- Appears indefinitely, button doesn't re-enable

**Causes:**
- CDN truly stuck (not responding)
- Browser timeout setting too high
- JavaScript error preventing completion

**Solutions:**
```javascript

// Try manual retry:

window.retryWebLLMLoad();



// Check for JavaScript errors:

// Press F12, look for red errors in Console



// Force manual timeout:

setTimeout(function() {

    console.log('Manual timeout fired');

    if (!window.webllm) {

        console.log('CDN still not loaded after 30 seconds, giving up');

        window.webllmError = 'Timeout after 30 seconds';

        window.webllmCDNLoading = false;

        // Click LOAD LOCAL MODEL button to show error

    }

}, 30000);

```

---

## Manual Retry Steps

**When to use:** If "Please wait..." message persists for >15 seconds

1. Open Console (F12)
2. Paste: `window.retryWebLLMLoad()`
3. Wait 5-10 seconds
4. Check console for: "WebLLM loaded from unpkg"
5. Try clicking "LOAD LOCAL MODEL" button again

**Expected result:**
- Console shows: `WebLLM loaded from unpkg X milliseconds`
- Status in Ahmad Bot changes from OFFLINE to READY

---

## Browser Console Command Reference

| Command | Purpose | Expected Output |
|---------|---------|-----------------|
| `window.webllmReady` | Check if loaded | `true` |
| `typeof window.webllm` | Check library exists | `object` |
| `window.webllmError` | Show error reason | `null` or error text |
| `Date.now() - window.webllmLoadTimestamp` | Check load time (ms) | `2500` (normal) or `>10000` (slow) |
| `window.retryWebLLMLoad()` | Manual retry | Loads from unpkg |
| `window.initAhmadUI()` | Re-initialize UI | No visible change |
| `window.ahmadJITUI.updateStatus('READY')` | Force status change | Status badge changes |

---

## Network Conditions to Test

These represent different scenarios:

```javascript

// Test 1: Slow CDN (simulates poor connection)

// Just wait longer (15+ seconds expected)



// Test 2: Timeout scenario

// CDN doesn't respond after 8 seconds → Fallback to unpkg



// Test 3: Corporate network

// May be blocked by proxy → Try personal WiFi



// Test 4: Mobile hotspot

// May have data limits → Download may be slow (5-10 min)

```

---

## Expected CDN Load Times

| Connection | Expected Time | Timeout |
|------------|---------------|---------|
| Fiber (100+ Mbps) | 2-3 seconds | 8 seconds |
| Broadband (10-50 Mbps) | 3-5 seconds | 8 seconds |
| DSL (3-10 Mbps) | 5-10 seconds | 8 seconds |
| Mobile 4G (5-20 Mbps) | 5-15 seconds | 8 seconds |
| Mobile 3G (<5 Mbps) | 15-30 seconds | 8 seconds (fallback) |
| Satellite | 30+ seconds | 8 seconds (fallback) |

**Note:** If CDN takes >8 seconds, automatic fallback to unpkg triggers.

---

## Full Diagnostic Report (Copy-Paste Everything)

Paste this entire script in console to get a complete report:

```javascript

console.log('=== WebLLM CDN FULL DIAGNOSTIC REPORT ===');

console.log('Timestamp:', new Date().toISOString());

console.log('');

console.log('=== Library Status ===');

console.log('window.webllm:', typeof window.webllm);

console.log('window.webllmReady:', window.webllmReady);

console.log('window.webllmCDNLoading:', window.webllmCDNLoading);

console.log('window.webllmError:', window.webllmError);

console.log('');

console.log('=== Performance ===');

console.log('Load time (ms):', window.webllmLoadTimestamp ? Date.now() - window.webllmLoadTimestamp : 'Not started');

console.log('');

console.log('=== MLCEngine ===');

if (window.webllm) {

    console.log('MLCEngine available:', typeof window.webllm.MLCEngine);

    console.log('MLCEngine is function:', typeof window.webllm.MLCEngine === 'function');

} else {

    console.log('WebLLM not loaded, cannot check MLCEngine');

}

console.log('');

console.log('=== Browser Support ===');

console.log('WebAssembly:', typeof WebAssembly);

console.log('Promise:', typeof Promise);

console.log('Async/Await:', typeof (async function(){}).constructor);

console.log('');

console.log('=== Recommendations ===');

if (window.webllmReady) {

    console.log('✓ WebLLM is ready. Try clicking LOAD LOCAL MODEL.');

} else if (window.webllmCDNLoading) {

    console.log('⟳ WebLLM still loading. Wait a moment and try again.');

    console.log('  OR manually retry: window.retryWebLLMLoad()');

} else if (window.webllmError) {

    console.log('✗ WebLLM failed to load. Error:', window.webllmError);

    console.log('  Trying manual retry: window.retryWebLLMLoad()');

} else {

    console.log('? WebLLM status unknown. Try refreshing the page.');

}

```

---

## Still Having Issues?

Try these in order:

1. **Hard Refresh** — Ctrl+Shift+R (Windows) / Cmd+Shift+R (Mac)
2. **Clear Cache** — DevTools > Settings > Network > Disable cache (checked)
3. **Manual Retry** — Paste: `window.retryWebLLMLoad()`
4. **Different Browser** — Try Chrome, Firefox, Safari, Edge
5. **Different Network** — Try phone hotspot or different WiFi
6. **Check Internet** — Open google.com, YouTube, etc. to confirm connection works

---

## For Developers

**Key Variables:**
- `window.webllmReady` — Boolean, true when library loaded
- `window.webllmError` — String, error reason if failed
- `window.webllmCDNLoading` — Boolean, true while loading
- `window.webllmLoadTimestamp` — Number, when loading started (Date.now())
- `window.webllmCallbacks` — Array, functions to call when ready

**Key Functions:**
- `window.retryWebLLMLoad()` — Manual fallback to unpkg
- `window.onWebLLMReady(callback)` — Register callback for when ready
- `window.fireWebLLMCallbacks()` — Internal, fires all callbacks

**CDN Load Timeout:** 8 seconds (after which fallback triggers)

---

**Last Updated:** July 27, 2026  
**Page:** https://snapkittywest.github.io/rowm-polymorphic-notebook/index-app.html