Common issues and solutions for Odoo PWA projects.

## What this command does:
- Lists common problems and their solutions
- Provides step-by-step debugging guides
- Offers troubleshooting workflows
- Helps diagnose connection, sync, and build issues
- Links to relevant documentation and tools

---

## Quick Diagnostic Checklist ✅

Before diving into specific issues, run through this checklist:

```
□ .env file exists and has all required variables
□ Odoo URL is correct and reachable
□ API key is valid and not expired
□ Database name is correct
□ Model name includes x_ prefix
□ Development server is running
□ No errors in browser console
□ Internet connection is working
□ Node.js version is 18 or higher
```

**Quick Test:** Run `/test-connection` to diagnose most issues automatically.

---

## Connection Issues 🔌

### Problem: Cannot connect to Odoo
**Symptoms:**
- "Connection refused" error
- "Network error" in console
- Timeout errors
- No data loading

**Solutions:**

#### 1. Verify Odoo URL
```bash
# Test if URL is reachable
curl -I https://yourcompany.odoo.com

# Expected: HTTP 200 or 301/302
```

**Common mistakes:**
- Missing `https://`
- Extra trailing slash
- Wrong subdomain
- Typo in URL

**Fix:**
```bash
# Wrong
VITE_ODOO_URL=yourcompany.odoo.com
VITE_ODOO_URL=https://yourcompany.odoo.com/

# Right
VITE_ODOO_URL=https://yourcompany.odoo.com
```

#### 2. Check firewall / VPN
- Try accessing Odoo URL in browser
- Disable VPN temporarily
- Check corporate firewall rules
- Try from different network

#### 3. Verify environment variables loaded
```javascript
// Add to your code temporarily
console.log('Odoo URL:', import.meta.env.VITE_ODOO_URL);
console.log('Database:', import.meta.env.VITE_ODOO_DB);
```

**If undefined:**
- Restart development server
- Check variable names (case-sensitive)
- Ensure variables start with `VITE_`

---

## Authentication Issues 🔐

### Problem: Invalid API key / Authentication failed
**Symptoms:**
- "Invalid credentials" error
- "Access denied" message
- 401 Unauthorized errors
- UID is null

**Solutions:**

#### 1. Regenerate API Key
1. Log into Odoo
2. Go to Settings → Users & Companies → Users
3. Open your user record
4. Go to "API Keys" tab
5. Click "New API Key"
6. Copy the key immediately (shown only once!)
7. Update `.env` file:
```bash
ODOO_API_KEY=your_new_api_key_here
```
8. Restart development server

#### 2. Verify username matches
```bash
# Username must match the API key owner
ODOO_USERNAME=john.doe@company.com  # ✅ Correct
ODOO_USERNAME=John Doe              # ❌ Wrong
```

#### 3. Check user permissions
- Ensure user has access to the model
- Verify read/write permissions
- Check if user account is active
- Verify not locked out

#### 4. Test authentication manually
```javascript
// In browser console
fetch('/api/odoo', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    action: 'search',
    model: 'res.partner',
    domain: [],
    fields: ['name'],
    limit: 1
  })
})
.then(r => r.json())
.then(console.log);
```

---

## Model Access Issues 📋

### Problem: Model not found / No records returned
**Symptoms:**
- "Model does not exist" error
- Empty array returned
- "Access rights" error
- Records don't appear

**Solutions:**

#### 1. Verify model name
```bash
# Check model name includes x_ prefix
VITE_MODEL_NAME=x_expense  # ✅ Correct
VITE_MODEL_NAME=expense    # ❌ Wrong
```

#### 2. Check model exists in Odoo
1. Log into Odoo
2. Go to Settings → Technical → Database Structure → Models
3. Search for your model name
4. Verify it exists and is active

#### 3. Check field names
```javascript
// Fields must use full name with x_studio_ prefix
const fields = [
  'x_studio_name',      // ✅ Correct
  'x_studio_amount',    // ✅ Correct
  'name',               // ❌ Wrong (unless it's a standard field)
  'amount'              // ❌ Wrong
];
```

#### 4. Verify permissions
- User must have read access to model
- Check access rights in Odoo Studio
- Verify record rules don't filter all records
- Test with admin user

#### 5. Check if model is published
- In Odoo Studio, verify model is not in draft mode
- Ensure model is accessible via API
- Check if model requires special access

---

## Sync Issues 🔄

### Problem: Data not syncing
**Symptoms:**
- Old data displayed
- Changes don't appear
- "Last synced" time not updating
- Background sync not working

**Solutions:**

#### 1. Check browser console
Look for:
- Network errors
- JavaScript errors
- CORS errors
- Authentication errors

#### 2. Verify sync mechanism
```javascript
// Check if sync is running
// Look for these console logs:
"Syncing x_expense..."
"Fetched X new records"
"Cache updated"
```

#### 3. Force refresh
```javascript
// In browser console
expenseCache.refresh();
```

#### 4. Clear cache and reload
```javascript
// In browser console
localStorage.clear();
// Then refresh page
```

#### 5. Check sync interval
```javascript
// Verify sync timer is running
// Default: 3 minutes (180,000ms)
// Look in cache store for:
setInterval(() => sync(), 180000);
```

#### 6. Test incremental sync
```javascript
// Check lastRecordId is updating
const cacheData = localStorage.getItem('expenseCache');
console.log(JSON.parse(cacheData));
// Should show: { lastRecordId: X, lastSyncTime: Y }
```

---

## Offline Mode Issues 📵

### Problem: Offline mode not working
**Symptoms:**
- App doesn't work without internet
- "No connection" errors when offline
- Service worker not registered
- Data not available offline

**Solutions:**

#### 1. Verify service worker registered
```javascript
// In browser console
navigator.serviceWorker.getRegistration()
  .then(reg => console.log('Service Worker:', reg));
```

#### 2. Check cache stores
```javascript
// Verify data is cached
localStorage.getItem('expenseCache');
// Should return JSON string

// Check IndexedDB
// Open DevTools → Application → IndexedDB
// Look for your database and tables
```

#### 3. Test offline mode
1. Load app while online
2. Open DevTools → Network tab
3. Enable "Offline" checkbox
4. Refresh page
5. App should still work

#### 4. Build and test production
```bash
# Offline mode works better in production build
npm run build
npm run preview
```

#### 5. Check manifest.json
Verify PWA manifest is correct:
- Located in `/static/manifest.json`
- Has correct `start_url`
- Has valid icons

---

## Build / Deployment Issues 🚀

### Problem: Build fails
**Symptoms:**
- `npm run build` returns errors
- TypeScript errors
- Module not found errors
- Build process hangs

**Solutions:**

#### 1. Check Node version
```bash
node --version
# Must be v18 or higher

# If too old:
nvm install 18
nvm use 18
```

#### 2. Clean install
```bash
rm -rf node_modules package-lock.json
npm install
```

#### 3. Check for errors
```bash
# Run build with verbose output
npm run build -- --verbose
```

#### 4. Verify environment variables
```bash
# For production build, set env vars:
VITE_ODOO_URL=https://yourcompany.odoo.com \
VITE_ODOO_DB=yourcompany-main \
npm run build
```

#### 5. Check imports
- Verify all imports are correct
- Check for circular dependencies
- Ensure all files exist

---

### Problem: Deployment fails
**Symptoms:**
- Vercel/Netlify build fails
- Environment variables not working
- 404 errors in production
- Blank page after deployment

**Solutions:**

#### 1. Set environment variables
In hosting dashboard:
- Add all `VITE_*` variables
- Add `ODOO_API_KEY`
- Add `ODOO_USERNAME`
- Redeploy after adding

#### 2. Check build logs
- Review deployment logs
- Look for specific errors
- Check Node version in platform

#### 3. Test build locally
```bash
npm run build
npm run preview
# Test at http://localhost:4173
```

#### 4. Verify base path
```javascript
// For GitHub Pages or subpath deployment
// vite.config.js
export default {
  base: '/your-repo-name/'
};
```

#### 5. Check API routes
- Ensure serverless functions deploy correctly
- Verify function size < 50MB
- Check function logs in platform dashboard

---

## Performance Issues ⚡

### Problem: App is slow
**Symptoms:**
- Slow initial load
- Laggy UI
- Long sync times
- High memory usage

**Solutions:**

#### 1. Optimize initial load
```javascript
// Limit initial fetch
const records = await odoo.searchRecords(
  model,
  [],
  fields,
  100  // Only fetch first 100
);
```

#### 2. Add pagination
```javascript
// Load more on scroll
let page = 1;
const pageSize = 20;

async function loadMore() {
  const offset = (page - 1) * pageSize;
  const more = await odoo.searchRecords(
    model, [], fields, pageSize, offset
  );
  page++;
  return more;
}
```

#### 3. Optimize bundle size
```bash
# Analyze bundle
npm run build -- --analyze

# Lazy load routes
// SvelteKit (automatic)
// React
const ExpenseList = lazy(() => import('./ExpenseList'));

// Vue
const ExpenseList = () => import('./ExpenseList.vue');
```

#### 4. Reduce sync frequency
```javascript
// Increase sync interval
const SYNC_INTERVAL = 5 * 60 * 1000; // 5 minutes instead of 3
```

#### 5. Optimize images
- Compress images before upload
- Use appropriate image formats
- Lazy load images

---

## Data Issues 📊

### Problem: Wrong data displayed
**Symptoms:**
- Incorrect values shown
- Missing fields
- Corrupted data
- Date format issues

**Solutions:**

#### 1. Clear cache
```javascript
expenseCache.clearCache();
expenseCache.refresh();
```

#### 2. Verify field mapping
```javascript
// Check if fields are correctly named
console.log(records[0]);
// Should show x_studio_* fields
```

#### 3. Check data types
```javascript
// Ensure correct types
const expense = {
  x_studio_amount: 45.50,        // number ✅
  x_studio_date: '2025-01-15',   // string (ISO) ✅
  x_studio_employee: [12, false] // Many2one ✅
};
```

#### 4. Format dates correctly
```javascript
// Store as ISO string
const dateString = '2025-01-15';

// Display formatted
new Date(dateString).toLocaleDateString();
```

#### 5. Handle Many2one fields
```javascript
// Many2one can be [id, name] or just id
function getPartnerId(field) {
  return Array.isArray(field) ? field[0] : field;
}

function getPartnerName(field) {
  return Array.isArray(field) ? field[1] : null;
}
```

---

## CORS Issues 🚫

### Problem: CORS error
**Symptoms:**
- "Blocked by CORS policy" in console
- Requests fail in browser but work in Postman
- Preflight errors (OPTIONS)

**Solutions:**

#### 1. Use server-side proxy (recommended)
All generated PWAs include server-side API routes. Ensure you're using them:
```javascript
// ✅ Good: Goes through server proxy
fetch('/api/odoo', { ... });

// ❌ Bad: Direct call to Odoo (CORS error)
fetch('https://yourcompany.odoo.com/jsonrpc', { ... });
```

#### 2. Verify API route works
```javascript
// Test in browser console
fetch('/api/odoo', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    action: 'search',
    model: 'res.partner',
    domain: [],
    fields: ['name'],
    limit: 1
  })
})
.then(r => r.json())
.then(console.log);
```

#### 3. Check if deployed correctly
- Verify serverless functions deployed
- Check function logs
- Ensure environment variables set

---

## Browser-Specific Issues 🌐

### Problem: Works in Chrome but not Safari/Firefox
**Symptoms:**
- Different behavior across browsers
- Safari-specific errors
- Mobile browser issues

**Solutions:**

#### 1. Check browser compatibility
- Test in multiple browsers
- Check for console errors in each
- Verify IndexedDB support

#### 2. Safari-specific
- Safari has stricter storage limits
- Check if localStorage/IndexedDB working
- Test in private mode

#### 3. Mobile browsers
- Test on actual devices
- Check responsive design
- Verify touch interactions work

---

## Debugging Tools & Commands 🔧

### Essential Commands
```bash
# Test connection
/test-connection

# View full help
/help

# See architecture details
/architecture

# Clear cache and start fresh
/clear-cache

# Fix sync issues
/fix-sync
```

### Browser DevTools
```javascript
// Network tab
// - See all API calls
// - Check request/response
// - View timing

// Console tab
// - See error messages
// - Run test commands
// - Inspect data

// Application tab
// - View localStorage
// - Inspect IndexedDB
// - Check Service Workers
// - View Cache Storage

// Performance tab
// - Profile slow operations
// - Find bottlenecks
```

### Useful Console Commands
```javascript
// View cache
localStorage.getItem('expenseCache');

// Clear cache
localStorage.clear();

// Force refresh
expenseCache.refresh();

// View current records
console.log($expenseCache); // SvelteKit

// Test API
fetch('/api/odoo', { /* ... */ })
  .then(r => r.json())
  .then(console.log);
```

---

## Getting Help 💬

### Before asking for help:
1. Run `/test-connection`
2. Check browser console for errors
3. Review this troubleshooting guide
4. Try solutions listed above
5. Test with minimal example

### When reporting issues:
Include:
- Exact error message
- Browser and version
- Node.js version
- Steps to reproduce
- What you've already tried
- Relevant code snippets

### Helpful resources:
- `/help` - Plugin documentation
- `/examples` - Usage examples
- `/architecture` - Design patterns
- `/api-reference` - API documentation
- Odoo docs: https://www.odoo.com/documentation/
- Framework docs (SvelteKit/React/Vue)

---

## Example prompts to use this command:
- `/troubleshoot` - Show troubleshooting guide
- User: "Why isn't my data syncing?"
- User: "I'm getting a connection error"
- User: "Help! Nothing works!"

## Still Stuck?
If these solutions don't help:
1. Run `/test-connection` for detailed diagnostics
2. Check generated project's CLAUDE.md
3. Review Odoo server logs
4. Test with different Odoo model
5. Try generating fresh project to compare

Most issues are related to configuration or permissions. Double-check your `.env` file and Odoo settings!