gh-jamshu-jamshi-marketplace-plugins-odoo-pwa-generator/commands/troubleshoot.md

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

# 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:

# 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

// 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:

ODOO_API_KEY=your_new_api_key_here

8. Restart development server

2. Verify username matches

# 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

// 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

# 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

// 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

// Check if sync is running
// Look for these console logs:
"Syncing x_expense..."
"Fetched X new records"
"Cache updated"

3. Force refresh

// In browser console
expenseCache.refresh();

4. Clear cache and reload

// In browser console
localStorage.clear();
// Then refresh page

5. Check sync interval

// Verify sync timer is running
// Default: 3 minutes (180,000ms)
// Look in cache store for:
setInterval(() => sync(), 180000);

6. Test incremental sync

// 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

// In browser console
navigator.serviceWorker.getRegistration()
  .then(reg => console.log('Service Worker:', reg));

2. Check cache stores

// 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

# 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

node --version
# Must be v18 or higher

# If too old:
nvm install 18
nvm use 18

2. Clean install

rm -rf node_modules package-lock.json
npm install

3. Check for errors

# Run build with verbose output
npm run build -- --verbose

4. Verify environment variables

# 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

npm run build
npm run preview
# Test at http://localhost:4173

4. Verify base path

// 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

// Limit initial fetch
const records = await odoo.searchRecords(
  model,
  [],
  fields,
  100  // Only fetch first 100
);

2. Add pagination

// 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

# 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

// 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

expenseCache.clearCache();
expenseCache.refresh();

2. Verify field mapping

// Check if fields are correctly named
console.log(records[0]);
// Should show x_studio_* fields

3. Check data types

// 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

// Store as ISO string
const dateString = '2025-01-15';

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

5. Handle Many2one fields

// 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:

// ✅ 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

// 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

# 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

// 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

// 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!