# Troubleshooting Guide
## Introduction
This comprehensive troubleshooting guide helps you quickly identify and resolve common issues when working with CUDA-Rust-WASM. From WebGPU compatibility problems to performance issues, this guide provides step-by-step solutions and debugging techniques.
## Table of Contents
1. [Quick Diagnostic Tools](#quick-diagnostic-tools)
2. [Installation and Setup Issues](#installation-and-setup-issues)
3. [WebGPU Compatibility Problems](#webgpu-compatibility-problems)
4. [Transpilation Errors](#transpilation-errors)
5. [Runtime Execution Issues](#runtime-execution-issues)
6. [Performance Problems](#performance-problems)
7. [Memory and Resource Issues](#memory-and-resource-issues)
8. [Browser-Specific Issues](#browser-specific-issues)
9. [Advanced Debugging Techniques](#advanced-debugging-techniques)
10. [Getting Help and Support](#getting-help-and-support)
## Quick Diagnostic Tools
### Automated System Check
Run this comprehensive system check to identify potential issues:
```javascript
// System diagnostic tool
class SystemDiagnostic {
constructor() {
this.results = {
browser: null,
webgpu: null,
hardware: null,
performance: null,
issues: [],
warnings: []
};
}
async runFullDiagnostic() {
console.log('š Running CUDA-Rust-WASM System Diagnostic...');
await this.checkBrowserCompatibility();
await this.checkWebGPUSupport();
await this.checkHardwareCapabilities();
await this.runPerformanceTests();
this.generateReport();
return this.results;
}
async checkBrowserCompatibility() {
const userAgent = navigator.userAgent;
const isChrome = userAgent.includes('Chrome');
const isFirefox = userAgent.includes('Firefox');
const isSafari = userAgent.includes('Safari') && !userAgent.includes('Chrome');
const isEdge = userAgent.includes('Edg');
this.results.browser = {
name: isChrome ? 'Chrome' : isFirefox ? 'Firefox' : isSafari ? 'Safari' : isEdge ? 'Edge' : 'Unknown',
version: this.extractBrowserVersion(userAgent),
userAgent: userAgent,
supported: isChrome || isFirefox || isSafari || isEdge
};\n \n if (!this.results.browser.supported) {\n this.results.issues.push({\n type: 'browser_compatibility',\n severity: 'critical',\n message: 'Unsupported browser detected',\n solution: 'Please use Chrome 113+, Firefox 115+, Safari 16.4+, or Edge 113+'\n });\n }\n \n // Check for required features\n const requiredFeatures = [\n { name: 'WebAssembly', check: () => typeof WebAssembly !== 'undefined' },\n { name: 'SharedArrayBuffer', check: () => typeof SharedArrayBuffer !== 'undefined' },\n { name: 'OffscreenCanvas', check: () => typeof OffscreenCanvas !== 'undefined' },\n { name: 'Worker', check: () => typeof Worker !== 'undefined' }\n ];\n \n for (const feature of requiredFeatures) {\n if (!feature.check()) {\n this.results.issues.push({\n type: 'missing_feature',\n severity: 'high',\n message: `${feature.name} not supported`,\n solution: `Enable ${feature.name} in browser settings or update browser`\n });\n }\n }\n }\n \n async checkWebGPUSupport() {\n if (!navigator.gpu) {\n this.results.webgpu = {\n supported: false,\n error: 'WebGPU not available'\n };\n \n this.results.issues.push({\n type: 'webgpu_unavailable',\n severity: 'critical',\n message: 'WebGPU is not supported in this browser',\n solution: 'Enable WebGPU in chrome://flags or use a browser with WebGPU support'\n });\n return;\n }\n \n try {\n const adapter = await navigator.gpu.requestAdapter();\n if (!adapter) {\n throw new Error('No WebGPU adapter available');\n }\n \n const device = await adapter.requestDevice();\n \n this.results.webgpu = {\n supported: true,\n adapter: {\n vendor: adapter.info?.vendor || 'Unknown',\n architecture: adapter.info?.architecture || 'Unknown',\n device: adapter.info?.device || 'Unknown',\n description: adapter.info?.description || 'Unknown'\n },\n limits: device.limits,\n features: Array.from(device.features),\n device: device\n };\n \n // Check for important features\n const recommendedFeatures = [\n 'float64',\n 'texture-compression-bc',\n 'texture-compression-etc2',\n 'texture-compression-astc',\n 'indirect-first-instance'\n ];\n \n for (const feature of recommendedFeatures) {\n if (!device.features.has(feature)) {\n this.results.warnings.push({\n type: 'missing_optional_feature',\n message: `Optional feature '${feature}' not supported`,\n impact: 'Some optimizations may not be available'\n });\n }\n }\n \n } catch (error) {\n this.results.webgpu = {\n supported: false,\n error: error.message\n };\n \n this.results.issues.push({\n type: 'webgpu_initialization',\n severity: 'critical',\n message: `WebGPU initialization failed: ${error.message}`,\n solution: 'Check graphics drivers and browser settings'\n });\n }\n }\n \n async checkHardwareCapabilities() {\n try {\n const hardware = await this.detectHardware();\n \n this.results.hardware = hardware;\n \n // Check minimum requirements\n if (hardware.memorySize < 1024 * 1024 * 1024) { // 1GB\n this.results.warnings.push({\n type: 'low_gpu_memory',\n message: 'Low GPU memory detected',\n impact: 'Large computations may fail'\n });\n }\n \n if (hardware.computeCapability < 5.0) {\n this.results.warnings.push({\n type: 'old_gpu',\n message: 'Older GPU detected',\n impact: 'Some features may not be available'\n });\n }\n \n } catch (error) {\n this.results.issues.push({\n type: 'hardware_detection',\n severity: 'medium',\n message: `Hardware detection failed: ${error.message}`,\n solution: 'Some optimizations may not work optimally'\n });\n }\n }\n \n async runPerformanceTests() {\n if (!this.results.webgpu?.supported) {\n return;\n }\n \n try {\n console.log('Running performance tests...');\n \n // Simple compute test\n const computeTest = await this.runComputeTest();\n \n // Memory bandwidth test\n const memoryTest = await this.runMemoryTest();\n \n this.results.performance = {\n compute: computeTest,\n memory: memoryTest,\n overall: (computeTest.score + memoryTest.score) / 2\n };\n \n if (this.results.performance.overall < 0.5) {\n this.results.warnings.push({\n type: 'low_performance',\n message: 'Performance tests indicate suboptimal GPU utilization',\n impact: 'Applications may run slower than expected'\n });\n }\n \n } catch (error) {\n this.results.issues.push({\n type: 'performance_test',\n severity: 'low',\n message: `Performance testing failed: ${error.message}`,\n solution: 'Performance may vary during actual usage'\n });\n }\n }\n \n async runComputeTest() {\n // Simple vector addition test\n const testKernel = `\n @compute @workgroup_size(256)\n fn test_compute(@builtin(global_invocation_id) global_id: vec3<u32>) {\n let i = global_id.x;\n if (i < arrayLength(&input)) {\n output[i] = input[i] * 2.0 + 1.0;\n }\n }\n `;\n \n const device = this.results.webgpu.device;\n const n = 1024 * 1024; // 1M elements\n \n // Create buffers\n const inputBuffer = device.createBuffer({\n size: n * 4,\n usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST\n });\n \n const outputBuffer = device.createBuffer({\n size: n * 4,\n usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC\n });\n \n // Create shader module\n const shaderModule = device.createShaderModule({ code: testKernel });\n \n // Create compute pipeline\n const computePipeline = device.createComputePipeline({\n layout: 'auto',\n compute: {\n module: shaderModule,\n entryPoint: 'test_compute'\n }\n });\n \n // Run test\n const start = performance.now();\n \n const commandEncoder = device.createCommandEncoder();\n const passEncoder = commandEncoder.beginComputePass();\n \n passEncoder.setPipeline(computePipeline);\n passEncoder.dispatchWorkgroups(Math.ceil(n / 256));\n passEncoder.end();\n \n device.queue.submit([commandEncoder.finish()]);\n await device.queue.onSubmittedWorkDone();\n \n const executionTime = performance.now() - start;\n \n // Calculate score (operations per millisecond)\n const opsPerMs = n / executionTime;\n const normalizedScore = Math.min(1.0, opsPerMs / 1000000); // Normalize to 1M ops/ms\n \n return {\n executionTime,\n opsPerMs,\n score: normalizedScore\n };\n }\n \n async runMemoryTest() {\n // Memory bandwidth test\n const device = this.results.webgpu.device;\n const size = 16 * 1024 * 1024; // 16MB\n \n const buffer = device.createBuffer({\n size,\n usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC\n });\n \n const data = new Uint8Array(size);\n \n const start = performance.now();\n device.queue.writeBuffer(buffer, 0, data);\n await device.queue.onSubmittedWorkDone();\n const transferTime = performance.now() - start;\n \n const bandwidthGBps = (size / (1024 * 1024 * 1024)) / (transferTime / 1000);\n const normalizedScore = Math.min(1.0, bandwidthGBps / 100); // Normalize to 100GB/s\n \n return {\n transferTime,\n bandwidthGBps,\n score: normalizedScore\n };\n }\n \n generateReport() {\n console.log('\\nšÆ CUDA-Rust-WASM Diagnostic Report\\n');\n \n // Browser info\n console.log('š± Browser:', this.results.browser.name, this.results.browser.version);\n \n // WebGPU status\n if (this.results.webgpu?.supported) {\n console.log('ā
WebGPU: Supported');\n console.log(' GPU:', this.results.webgpu.adapter.vendor, this.results.webgpu.adapter.device);\n } else {\n console.log('ā WebGPU: Not supported');\n }\n \n // Hardware info\n if (this.results.hardware) {\n console.log('š„ļø Hardware:');\n console.log(' Compute Capability:', this.results.hardware.computeCapability);\n console.log(' Memory:', (this.results.hardware.memorySize / (1024*1024*1024)).toFixed(1), 'GB');\n }\n \n // Performance\n if (this.results.performance) {\n console.log('ā” Performance Score:', (this.results.performance.overall * 100).toFixed(1) + '%');\n }\n \n // Issues\n if (this.results.issues.length > 0) {\n console.log('\\nā Issues Found:');\n for (const issue of this.results.issues) {\n console.log(` ${issue.severity.toUpperCase()}: ${issue.message}`);\n console.log(` Solution: ${issue.solution}`);\n }\n }\n \n // Warnings\n if (this.results.warnings.length > 0) {\n console.log('\\nā ļø Warnings:');\n for (const warning of this.results.warnings) {\n console.log(` ${warning.message}`);\n if (warning.impact) {\n console.log(` Impact: ${warning.impact}`);\n }\n }\n }\n \n if (this.results.issues.length === 0 && this.results.warnings.length === 0) {\n console.log('\\nā
No issues detected! System is ready for CUDA-Rust-WASM.');\n }\n }\n \n extractBrowserVersion(userAgent) {\n const patterns = {\n Chrome: /Chrome\\/(\\d+\\.\\d+)/,\n Firefox: /Firefox\\/(\\d+\\.\\d+)/,\n Safari: /Version\\/(\\d+\\.\\d+)/,\n Edge: /Edg\\/(\\d+\\.\\d+)/\n };\n \n for (const [browser, pattern] of Object.entries(patterns)) {\n const match = userAgent.match(pattern);\n if (match) {\n return match[1];\n }\n }\n \n return 'Unknown';\n }\n \n async detectHardware() {\n // Simplified hardware detection\n return {\n computeCapability: 7.0, // Assume modern GPU\n memorySize: 4 * 1024 * 1024 * 1024, // 4GB\n coreCount: 2048,\n maxThreadsPerBlock: 1024\n };\n }\n}\n\n// Run diagnostic\nconst diagnostic = new SystemDiagnostic();\nconst results = await diagnostic.runFullDiagnostic();\n```\n\n### Quick Health Check\n\n```bash\n# Run quick system check\nnpx cuda-rust-wasm doctor\n\n# Check specific component\nnpx cuda-rust-wasm doctor --webgpu\nnpx cuda-rust-wasm doctor --hardware\nnpx cuda-rust-wasm doctor --performance\n```\n\n## Installation and Setup Issues\n\n### Issue: NPX Command Not Found\n\n**Symptoms:**\n```bash\nnpx: command not found\n```\n\n**Solutions:**\n\n1. **Install Node.js:**\n ```bash\n # Download from https://nodejs.org/\n # Or use package manager:\n \n # macOS\n brew install node\n \n # Ubuntu/Debian\n sudo apt install nodejs npm\n \n # Windows\n choco install nodejs\n ```\n\n2. **Update Node.js:**\n ```bash\n # Check version\n node --version\n npm --version\n \n # Update if needed\n npm install -g npm@latest\n ```\n\n3. **Alternative Installation:**\n ```bash\n # Install globally instead\n npm install -g cuda-rust-wasm\n cuda-rust-wasm --version\n ```\n\n### Issue: Package Installation Fails\n\n**Symptoms:**\n```\nERR! code EACCES\nERR! permission denied\n```\n\n**Solutions:**\n\n1. **Fix npm permissions (macOS/Linux):**\n ```bash\n # Set npm to use different directory\n mkdir ~/.npm-global\n npm config set prefix '~/.npm-global'\n echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc\n source ~/.bashrc\n ```\n\n2. **Use sudo (not recommended):**\n ```bash\n sudo npm install -g cuda-rust-wasm\n ```\n\n3. **Use npx (recommended):**\n ```bash\n # No installation needed\n npx cuda-rust-wasm@latest --version\n ```\n\n### Issue: Build Dependencies Missing\n\n**Symptoms:**\n```\nnode-gyp rebuild failed\npython: command not found\n```\n\n**Solutions:**\n\n1. **Install build tools:**\n ```bash\n # Windows\n npm install --global windows-build-tools\n \n # macOS\n xcode-select --install\n \n # Ubuntu/Debian\n sudo apt install build-essential python3-dev\n ```\n\n2. **Set Python path:**\n ```bash\n npm config set python python3\n ```\n\n## WebGPU Compatibility Problems\n\n### Issue: WebGPU Not Supported\n\n**Symptoms:**\n```javascript\nnavigator.gpu is undefined\n```\n\n**Solutions:**\n\n1. **Enable WebGPU in Chrome:**\n - Go to `chrome://flags/`\n - Search for \"WebGPU\"\n - Enable \"Unsafe WebGPU\"\n - Restart browser\n\n2. **Update browser:**\n - Chrome 113+ required\n - Firefox 115+ required\n - Safari 16.4+ required\n - Edge 113+ required\n\n3. **Check GPU drivers:**\n ```bash\n # Windows\n dxdiag\n \n # macOS\n system_profiler SPDisplaysDataType\n \n # Linux\n lspci | grep -i vga\n nvidia-smi # for NVIDIA\n ```\n\n4. **Fallback to WebAssembly:**\n ```javascript\n if (!navigator.gpu) {\n console.log('WebGPU not available, using WASM fallback');\n // Initialize WASM runtime instead\n }\n ```\n\n### Issue: WebGPU Adapter Request Fails\n\n**Symptoms:**\n```javascript\nrequestAdapter() returns null\n```\n\n**Solutions:**\n\n1. **Check hardware compatibility:**\n ```javascript\n const adapter = await navigator.gpu.requestAdapter({\n powerPreference: 'high-performance'\n });\n \n if (!adapter) {\n // Try with different preferences\n const fallbackAdapter = await navigator.gpu.requestAdapter({\n powerPreference: 'low-power'\n });\n }\n ```\n\n2. **Update graphics drivers:**\n - Visit GPU manufacturer website\n - Download latest drivers\n - Restart system\n\n3. **Check browser flags:**\n - `chrome://gpu/` for GPU status\n - Look for WebGPU support status\n\n### Issue: Device Creation Fails\n\n**Symptoms:**\n```javascript\nrequestDevice() throws error\n```\n\n**Solutions:**\n\n1. **Request with minimal features:**\n ```javascript\n try {\n const device = await adapter.requestDevice();\n } catch (error) {\n console.error('Device request failed:', error);\n // Try with reduced requirements\n const device = await adapter.requestDevice({\n requiredLimits: {\n maxComputeWorkgroupSizeX: 256\n }\n });\n }\n ```\n\n2. **Check device limits:**\n ```javascript\n console.log('Adapter limits:', adapter.limits);\n console.log('Adapter features:', adapter.features);\n ```\n\n## Transpilation Errors\n\n### Issue: CUDA Syntax Not Supported\n\n**Symptoms:**\n```\nUnsupported CUDA feature: dynamic parallelism\nError: __device__ functions not supported\n```\n\n**Solutions:**\n\n1. **Check compatibility matrix:**\n ```bash\n npx cuda-rust-wasm analyze kernel.cu --compatibility\n ```\n\n2. **Rewrite unsupported features:**\n ```cuda\n // Instead of dynamic parallelism\n __global__ void parent_kernel() {\n // Launch child kernel - NOT SUPPORTED\n child_kernel<<<1, 1>>>();\n }\n \n // Use restructured approach\n __global__ void unified_kernel() {\n // Combine logic in single kernel\n }\n ```\n\n3. **Use alternative patterns:**\n ```cuda\n // Instead of __device__ functions\n __device__ float device_function(float x) {\n return x * 2.0f;\n }\n \n // Use inline functions\n __forceinline__ __device__ float inline_function(float x) {\n return x * 2.0f;\n }\n ```\n\n### Issue: Include File Errors\n\n**Symptoms:**\n```\nfatal error: cuda_runtime.h: No such file or directory\n```\n\n**Solutions:**\n\n1. **Remove CUDA includes:**\n ```cuda\n // Remove these lines\n #include <cuda_runtime.h>\n #include <device_launch_parameters.h>\n \n // Keep only kernel code\n __global__ void my_kernel() {\n // kernel implementation\n }\n ```\n\n2. **Use transpiler-compatible headers:**\n ```cuda\n // Instead of CUDA headers, use built-in types\n // float, int, etc. are automatically available\n ```\n\n### Issue: Template/Generic Code Errors\n\n**Symptoms:**\n```\nTemplate instantiation failed\nGeneric type not supported\n```\n\n**Solutions:**\n\n1. **Specialize templates:**\n ```cuda\n // Instead of generic template\n template<typename T>\n __global__ void generic_kernel(T* data) { }\n \n // Use specific types\n __global__ void float_kernel(float* data) { }\n __global__ void int_kernel(int* data) { }\n ```\n\n2. **Use preprocessor:**\n ```cuda\n #define KERNEL_TYPE float\n \n __global__ void typed_kernel(KERNEL_TYPE* data) {\n // implementation\n }\n ```\n\n## Runtime Execution Issues\n\n### Issue: Kernel Launch Fails\n\n**Symptoms:**\n```javascript\nError: Kernel dispatch failed\nWebGPU validation error\n```\n\n**Solutions:**\n\n1. **Check buffer bindings:**\n ```javascript\n // Ensure all buffers are properly bound\n kernel.setBuffer(0, inputBuffer);\n kernel.setBuffer(1, outputBuffer);\n \n // Check buffer sizes match kernel expectations\n console.log('Buffer sizes:', {\n input: inputBuffer.size,\n output: outputBuffer.size\n });\n ```\n\n2. **Validate dispatch dimensions:**\n ```javascript\n const maxWorkgroupSize = device.limits.maxComputeWorkgroupSizeX;\n const workgroupSize = Math.min(256, maxWorkgroupSize);\n \n const numWorkgroups = Math.ceil(dataSize / workgroupSize);\n \n if (numWorkgroups > device.limits.maxComputeWorkgroupsPerDimension) {\n throw new Error('Too many workgroups required');\n }\n \n await kernel.dispatch(numWorkgroups, 1, 1);\n ```\n\n3. **Enable debug mode:**\n ```javascript\n const kernel = await createWebGPUKernel(device, code, {\n debugMode: true,\n validateBuffers: true\n });\n ```\n\n### Issue: Memory Access Violations\n\n**Symptoms:**\n```\nBuffer access out of bounds\nMemory corruption detected\n```\n\n**Solutions:**\n\n1. **Add bounds checking:**\n ```cuda\n __global__ void safe_kernel(float* data, int n) {\n int idx = blockIdx.x * blockDim.x + threadIdx.x;\n \n // Always check bounds\n if (idx < n) {\n data[idx] = data[idx] * 2.0f;\n }\n }\n ```\n\n2. **Validate buffer sizes:**\n ```javascript\n // Ensure buffer is large enough\n const requiredSize = dataLength * 4; // float32\n if (buffer.size < requiredSize) {\n throw new Error(`Buffer too small: ${buffer.size} < ${requiredSize}`);\n }\n ```\n\n### Issue: Synchronization Problems\n\n**Symptoms:**\n```\nRace condition detected\nInconsistent results\n```\n\n**Solutions:**\n\n1. **Add proper synchronization:**\n ```cuda\n __global__ void synchronized_kernel() {\n __shared__ float shared_data[256];\n \n // Load data\n shared_data[threadIdx.x] = input[threadIdx.x];\n \n // ALWAYS synchronize after shared memory writes\n __syncthreads();\n \n // Use data\n output[threadIdx.x] = shared_data[threadIdx.x] * 2.0f;\n }\n ```\n\n2. **Use memory barriers:**\n ```cuda\n __global__ void barrier_kernel() {\n // Ensure memory operations are visible\n __threadfence();\n }\n ```\n\n## Performance Problems\n\n### Issue: Slow Execution\n\n**Symptoms:**\n- Execution time much higher than expected\n- Low GPU utilization\n- Poor performance compared to native CUDA\n\n**Diagnostic Steps:**\n\n1. **Profile the kernel:**\n ```javascript\n const profiler = kernel.createProfiler();\n profiler.start();\n \n await kernel.dispatch(gridSize, 1, 1);\n \n const profile = profiler.stop();\n console.log('Profiling results:', {\n executionTime: profile.executionTime,\n memoryBandwidth: profile.memoryBandwidth,\n occupancy: profile.occupancy\n });\n ```\n\n2. **Analyze bottlenecks:**\n ```bash\n npx cuda-rust-wasm analyze kernel.cu --performance-focus\n ```\n\n**Solutions:**\n\n1. **Optimize memory access:**\n ```cuda\n // Ensure coalesced memory access\n __global__ void coalesced_kernel(float* data) {\n int idx = blockIdx.x * blockDim.x + threadIdx.x;\n // Consecutive threads access consecutive memory\n data[idx] = data[idx] * 2.0f;\n }\n ```\n\n2. **Increase occupancy:**\n ```javascript\n // Try different workgroup sizes\n const workgroupSizes = [64, 128, 256, 512];\n let bestPerformance = 0;\n let optimalSize = 256;\n \n for (const size of workgroupSizes) {\n const kernel = await createWebGPUKernel(device, code, {\n workgroupSize: [size, 1, 1]\n });\n \n const performance = await benchmarkKernel(kernel);\n if (performance > bestPerformance) {\n bestPerformance = performance;\n optimalSize = size;\n }\n }\n ```\n\n3. **Use shared memory effectively:**\n ```cuda\n __global__ void optimized_kernel() {\n __shared__ float shared_data[256];\n \n // Load data into shared memory\n shared_data[threadIdx.x] = global_data[threadIdx.x];\n __syncthreads();\n \n // Perform multiple operations on shared data\n float result = shared_data[threadIdx.x];\n result = result * 2.0f + 1.0f;\n result = sqrtf(result);\n \n global_data[threadIdx.x] = result;\n }\n ```\n\n### Issue: Memory Bandwidth Underutilization\n\n**Solutions:**\n\n1. **Vectorize memory operations:**\n ```cuda\n __global__ void vectorized_kernel(float4* data) {\n int idx = blockIdx.x * blockDim.x + threadIdx.x;\n \n // Process 4 elements at once\n float4 vec = data[idx];\n vec.x *= 2.0f;\n vec.y *= 2.0f;\n vec.z *= 2.0f;\n vec.w *= 2.0f;\n data[idx] = vec;\n }\n ```\n\n2. **Optimize data layout:**\n ```javascript\n // Use structure of arrays instead of array of structures\n // Better: separate arrays for each component\n const positions_x = new Float32Array(n);\n const positions_y = new Float32Array(n);\n const positions_z = new Float32Array(n);\n \n // Worse: interleaved data\n const positions_xyz = new Float32Array(n * 3); // x,y,z,x,y,z...\n ```\n\n## Memory and Resource Issues\n\n### Issue: Out of Memory Errors\n\n**Symptoms:**\n```\nWebGPU: Out of memory\nBuffer allocation failed\n```\n\n**Solutions:**\n\n1. **Check available memory:**\n ```javascript\n console.log('Device limits:', device.limits);\n console.log('Max buffer size:', device.limits.maxBufferSize);\n console.log('Max storage buffer binding size:', device.limits.maxStorageBufferBindingSize);\n ```\n\n2. **Implement chunked processing:**\n ```javascript\n async function processLargeDataset(data, chunkSize = 1024 * 1024) {\n const results = [];\n \n for (let i = 0; i < data.length; i += chunkSize) {\n const chunk = data.slice(i, i + chunkSize);\n const result = await processChunk(chunk);\n results.push(result);\n \n // Allow garbage collection\n await new Promise(resolve => setTimeout(resolve, 0));\n }\n \n return results.flat();\n }\n ```\n\n3. **Use memory pools:**\n ```javascript\n class MemoryPool {\n constructor(device, bufferSize, poolSize = 10) {\n this.device = device;\n this.bufferSize = bufferSize;\n this.availableBuffers = [];\n this.usedBuffers = new Set();\n \n // Pre-allocate buffers\n for (let i = 0; i < poolSize; i++) {\n const buffer = device.createBuffer({\n size: bufferSize,\n usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC\n });\n this.availableBuffers.push(buffer);\n }\n }\n \n getBuffer() {\n if (this.availableBuffers.length === 0) {\n throw new Error('No buffers available');\n }\n \n const buffer = this.availableBuffers.pop();\n this.usedBuffers.add(buffer);\n return buffer;\n }\n \n releaseBuffer(buffer) {\n this.usedBuffers.delete(buffer);\n this.availableBuffers.push(buffer);\n }\n }\n ```\n\n### Issue: Memory Leaks\n\n**Symptoms:**\n- Gradually increasing memory usage\n- Browser becomes slow over time\n- Eventually crashes with out of memory\n\n**Solutions:**\n\n1. **Explicit resource cleanup:**\n ```javascript\n class ResourceManager {\n constructor() {\n this.buffers = new Set();\n this.kernels = new Set();\n }\n \n trackBuffer(buffer) {\n this.buffers.add(buffer);\n return buffer;\n }\n \n trackKernel(kernel) {\n this.kernels.add(kernel);\n return kernel;\n }\n \n cleanup() {\n // Destroy all tracked resources\n for (const buffer of this.buffers) {\n buffer.destroy();\n }\n \n for (const kernel of this.kernels) {\n kernel.destroy();\n }\n \n this.buffers.clear();\n this.kernels.clear();\n }\n }\n \n // Use in application\n const resourceManager = new ResourceManager();\n \n // Always cleanup when done\n window.addEventListener('beforeunload', () => {\n resourceManager.cleanup();\n });\n ```\n\n2. **Use WeakRef for automatic cleanup:**\n ```javascript\n class AutoCleanupBuffer {\n constructor(device, size, usage) {\n this.buffer = device.createBuffer({ size, usage });\n this.weakRef = new WeakRef(this.buffer);\n \n // Schedule cleanup check\n setTimeout(() => this.checkCleanup(), 1000);\n }\n \n checkCleanup() {\n const buffer = this.weakRef.deref();\n if (!buffer) {\n // Buffer was garbage collected, clean up resources\n console.log('Buffer automatically cleaned up');\n }\n }\n }\n ```\n\n## Browser-Specific Issues\n\n### Chrome Issues\n\n1. **WebGPU flags not enabled:**\n - Visit `chrome://flags/`\n - Enable \"Unsafe WebGPU\"\n - Enable \"WebGPU Developer Features\"\n - Restart browser\n\n2. **GPU process crashes:**\n - Check `chrome://gpu/`\n - Look for \"GPU process crashed\"\n - Try disabling GPU acceleration temporarily\n - Update graphics drivers\n\n### Firefox Issues\n\n1. **WebGPU not available:**\n - Visit `about:config`\n - Set `dom.webgpu.enabled` to `true`\n - Restart browser\n\n2. **Limited feature support:**\n - Some WebGPU features may not be implemented yet\n - Check Firefox nightly for latest features\n\n### Safari Issues\n\n1. **WebGPU experimental:**\n - Enable \"Develop\" menu in Preferences\n - Check \"Experimental Features\" > \"WebGPU\"\n - May require Safari Technology Preview\n\n2. **Limited memory:**\n - Safari has stricter memory limits\n - Use smaller buffer sizes\n - Implement more aggressive cleanup\n\n## Advanced Debugging Techniques\n\n### GPU Debugging\n\n```javascript\n// Advanced GPU debugging\nclass GPUDebugger {\n constructor(device) {\n this.device = device;\n this.capturedFrames = [];\n }\n \n async captureFrame(kernel, inputs) {\n // Enable debug mode\n this.device.pushErrorScope('validation');\n this.device.pushErrorScope('out-of-memory');\n this.device.pushErrorScope('internal');\n \n try {\n // Execute kernel with debugging\n const result = await kernel.execute(inputs);\n \n // Check for errors\n const errors = await Promise.all([\n this.device.popErrorScope(),\n this.device.popErrorScope(),\n this.device.popErrorScope()\n ]);\n \n if (errors.some(e => e)) {\n console.error('GPU errors detected:', errors);\n }\n \n return result;\n \n } catch (error) {\n console.error('GPU execution failed:', error);\n throw error;\n }\n }\n \n async validateBuffers(buffers) {\n for (const [index, buffer] of buffers.entries()) {\n if (buffer.mapState === 'mapped') {\n console.warn(`Buffer ${index} is already mapped`);\n }\n \n if (buffer.size === 0) {\n console.error(`Buffer ${index} has zero size`);\n }\n }\n }\n \n generateDebugReport(kernel, performance) {\n return {\n timestamp: new Date().toISOString(),\n kernel: {\n code: kernel.source,\n workgroupSize: kernel.workgroupSize,\n bufferCount: kernel.buffers.length\n },\n performance: {\n executionTime: performance.executionTime,\n memoryBandwidth: performance.memoryBandwidth,\n occupancy: performance.occupancy\n },\n device: {\n limits: this.device.limits,\n features: Array.from(this.device.features)\n }\n };\n }\n}\n```\n\n### Performance Debugging\n\n```javascript\n// Performance profiling and debugging\nclass PerformanceDebugger {\n constructor() {\n this.samples = [];\n this.isRecording = false;\n }\n \n startRecording() {\n this.isRecording = true;\n this.samples = [];\n console.log('Performance recording started');\n }\n \n recordSample(name, startTime, endTime, metadata = {}) {\n if (!this.isRecording) return;\n \n this.samples.push({\n name,\n duration: endTime - startTime,\n startTime,\n endTime,\n metadata\n });\n }\n \n stopRecording() {\n this.isRecording = false;\n console.log(`Performance recording stopped. ${this.samples.length} samples collected.`);\n return this.analyzePerformance();\n }\n \n analyzePerformance() {\n const analysis = {\n totalSamples: this.samples.length,\n totalTime: 0,\n breakdown: {},\n bottlenecks: [],\n recommendations: []\n };\n \n // Calculate totals and breakdown\n for (const sample of this.samples) {\n analysis.totalTime += sample.duration;\n \n if (!analysis.breakdown[sample.name]) {\n analysis.breakdown[sample.name] = {\n count: 0,\n totalTime: 0,\n avgTime: 0,\n minTime: Infinity,\n maxTime: 0\n };\n }\n \n const breakdown = analysis.breakdown[sample.name];\n breakdown.count++;\n breakdown.totalTime += sample.duration;\n breakdown.minTime = Math.min(breakdown.minTime, sample.duration);\n breakdown.maxTime = Math.max(breakdown.maxTime, sample.duration);\n breakdown.avgTime = breakdown.totalTime / breakdown.count;\n }\n \n // Identify bottlenecks\n for (const [name, data] of Object.entries(analysis.breakdown)) {\n if (data.totalTime > analysis.totalTime * 0.3) { // 30% of total time\n analysis.bottlenecks.push({\n operation: name,\n timePercentage: (data.totalTime / analysis.totalTime * 100).toFixed(1),\n avgDuration: data.avgTime.toFixed(2)\n });\n }\n }\n \n // Generate recommendations\n analysis.recommendations = this.generateRecommendations(analysis);\n \n return analysis;\n }\n \n generateRecommendations(analysis) {\n const recommendations = [];\n \n // Check for memory bottlenecks\n const memoryOps = analysis.breakdown['memory_transfer'];\n if (memoryOps && memoryOps.totalTime > analysis.totalTime * 0.4) {\n recommendations.push({\n category: 'memory',\n issue: 'Memory transfers dominate execution time',\n suggestion: 'Consider keeping data on GPU longer or using streaming'\n });\n }\n \n // Check for small kernel launches\n const kernelOps = analysis.breakdown['kernel_launch'];\n if (kernelOps && kernelOps.avgTime < 0.1) {\n recommendations.push({\n category: 'performance',\n issue: 'Very fast kernel launches detected',\n suggestion: 'Consider kernel fusion or larger workgroup sizes'\n });\n }\n \n return recommendations;\n }\n}\n\n// Usage\nconst debugger = new PerformanceDebugger();\ndebugger.startRecording();\n\n// Your GPU operations here\nconst start = performance.now();\nawait kernel.execute(data);\nconst end = performance.now();\ndebugger.recordSample('kernel_execution', start, end, { dataSize: data.length });\n\nconst analysis = debugger.stopRecording();\nconsole.log('Performance analysis:', analysis);\n```\n\n## Getting Help and Support\n\n### Community Resources\n\n1. **Discord Community:**\n - Join: [https://discord.gg/vibecast](https://discord.gg/vibecast)\n - Channels: #cuda-rust-wasm, #support, #performance\n - Real-time help from developers and community\n\n2. **GitHub Issues:**\n - Bug reports: [https://github.com/vibecast/cuda-rust-wasm/issues](https://github.com/vibecast/cuda-rust-wasm/issues)\n - Feature requests: Use issue templates\n - Search existing issues first\n\n3. **Documentation:**\n - Full docs: [https://docs.vibecast.io/cuda-rust-wasm](https://docs.vibecast.io/cuda-rust-wasm)\n - API reference: [docs/API.md](./API.md)\n - Tutorials: [docs/tutorials/](./tutorials/)\n\n### Creating Bug Reports\n\nWhen reporting issues, include:\n\n1. **System information:**\n ```bash\n npx cuda-rust-wasm doctor --export > system-info.json\n ```\n\n2. **Minimal reproduction case:**\n ```javascript\n // Minimal code that reproduces the issue\n const kernel = `\n __global__ void problem_kernel() {\n // Minimal example\n }\n `;\n \n // Steps to reproduce\n const result = await transpileCuda(kernel);\n // Error occurs here\n ```\n\n3. **Error messages:**\n - Full error stack traces\n - Browser console output\n - WebGPU validation errors\n\n4. **Expected vs actual behavior:**\n - What you expected to happen\n - What actually happened\n - Screenshots if relevant\n\n### Performance Issue Reports\n\nFor performance problems, include:\n\n1. **Benchmark results:**\n ```bash\n npx cuda-rust-wasm benchmark kernel.cu --export > benchmark.json\n ```\n\n2. **Profiling data:**\n ```javascript\n const profile = await kernel.getDetailedProfile();\n console.log('Profile data:', JSON.stringify(profile, null, 2));\n ```\n\n3. **Hardware specifications:**\n - GPU model and driver version\n - Available memory\n - Browser version\n\n### Enterprise Support\n\nFor production deployments:\n\n- **Priority Support:** enterprise@vibecast.io\n- **Consulting Services:** consulting@vibecast.io\n- **Training Workshops:** training@vibecast.io\n- **Custom Optimization:** optimization@vibecast.io\n\n### Self-Help Checklist\n\nBefore asking for help:\n\n- [ ] Run `npx cuda-rust-wasm doctor` to check system\n- [ ] Check the [FAQ](./FAQ.md) for common questions\n- [ ] Search existing GitHub issues\n- [ ] Try the troubleshooting steps in this guide\n- [ ] Test with a minimal reproduction case\n- [ ] Check browser console for error messages\n- [ ] Update to the latest version of cuda-rust-wasm\n\n---\n\nThis troubleshooting guide covers the most common issues you might encounter. If you can't find a solution here, don't hesitate to reach out to the community or file an issue with detailed information about your problem.