Troubleshooting Guide

Troubleshooting Guide

Solutions to common issues when developing and deploying ImageBot.

Installation Issues

Node Version Mismatch

Error:

error imagebot@0.0.1: The engine "node" is incompatible with this module.

Solution:

# Check Node version
node --version

# Should be 18.x or higher
# Install Node 18+ if needed
nvm install 18
nvm use 18

Wrangler Login Fails

Error:

Error: Failed to login. Please try again.

Solution:

# Clear Wrangler cache
rm -rf ~/.wrangler

# Try login again
wrangler login

# If still fails, use API token
wrangler login --api-key YOUR_API_KEY

Package Installation Errors

Error:

npm ERR! ERESOLVE unable to resolve dependency tree

Solution:

# Clear npm cache
npm cache clean --force

# Delete node_modules and package-lock.json
rm -rf node_modules package-lock.json

# Reinstall with legacy peer deps
npm install --legacy-peer-deps

Database Issues

Foreign Key Constraint Errors

Error:

SQLITE_ERROR: no such column: team_id at offset 69

Solution: Use the minimal schema versions that avoid foreign key constraints:

# Use teams-minimal.sql instead of teams-schema.sql
wrangler d1 execute imagebot-db --remote --file database/teams-minimal.sql

Why: Cloudflare D1 has limitations with ALTER TABLE and complex foreign key constraints.

Database Not Found

Error:

Error: Database binding 'DB' not found

Solution:

1. Verify database exists:

wrangler d1 list

2. Check wrangler.toml has correct binding:

[[d1_databases]]
binding = "DB"
database_name = "imagebot-db"
database_id = "your-database-id-here"

3. Ensure you’re running worker dev server:

npm run worker:dev

Schema Migration Fails

Error:

Error: table 'users' already exists

Solution:

Option 1: Use IF NOT EXISTS in schema (already included in schema-init.sql)

CREATE TABLE IF NOT EXISTS users (...)

Option 2: Drop and recreate (⚠️ DELETES ALL DATA):

# Export data first
wrangler d1 export imagebot-db --output backup.sql

# Delete and recreate database
wrangler d1 delete imagebot-db
wrangler d1 create imagebot-db

# Apply schema
wrangler d1 execute imagebot-db --remote --file database/schema-init.sql

Worker Issues

Worker Deployment Fails

Error:

Error: Script startup exceeded CPU time limit

Solution:

1. Remove unnecessary imports:

// Remove heavy libraries not used in production
// Check worker/index.ts for large dependencies

2. Optimize initialization:

// Move heavy operations out of global scope
// Lazy load modules only when needed

3. Check bundle size:

wrangler publish --dry-run --outdir=dist
ls -lh dist

CORS Errors

Error (Browser Console):

Access to fetch at 'https://worker.dev/api/generate' from origin 'http://localhost:4321'
has been blocked by CORS policy

Solution:

Update worker/index.ts CORS headers:

const corsHeaders = {
  'Access-Control-Allow-Origin': '*', // Or specific origin
  'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS',
  'Access-Control-Allow-Headers': 'Content-Type, Authorization',
};

// Handle OPTIONS preflight
if (request.method === 'OPTIONS') {
  return new Response(null, { headers: corsHeaders });
}

// Add to all responses
return new Response(JSON.stringify(data), {
  headers: { ...corsHeaders, 'Content-Type': 'application/json' }
});

401 Unauthorized Errors

Error:

{"error": "Unauthorized"}

Solution:

1. Check JWT token is being sent:

// In browser console
localStorage.getItem('token')

2. Verify Authorization header:

fetch('https://worker.dev/api/images', {
  headers: {
    'Authorization': `Bearer ${localStorage.getItem('token')}`
  }
})

3. Check token hasn’t expired:

// Decode JWT (payload is middle part)
const payload = JSON.parse(atob(token.split('.')[1]));
console.log('Expires:', new Date(payload.exp * 1000));

4. Verify JWT_SECRET is set:

wrangler secret list

Worker Not Updating

Error: Changes to worker code don’t appear after deployment.

Solution:

1. Clear Cloudflare cache:

# Purge cache via API
curl -X POST "https://api.cloudflare.com/client/v4/zones/ZONE_ID/purge_cache" \
  -H "Authorization: Bearer API_TOKEN" \
  -d '{"purge_everything":true}'

2. Hard refresh browser:

• Chrome: Cmd+Shift+R (Mac) or Ctrl+Shift+R (Windows)

3. Check deployment succeeded:

wrangler tail imagebot-worker
# Trigger request and watch for logs

Frontend Issues

API_URL Not Defined

Error:

TypeError: Cannot read property 'get' of undefined

Solution:

1. Create .env file:

cp .env.example .env

2. Set API URL:

PUBLIC_API_URL=http://localhost:8787

3. Restart dev server:

npm run dev

Images Not Loading

Error: Images show broken image icon or 404.

Solution:

1. Check R2 bucket exists:

wrangler r2 bucket list

2. Verify R2 binding in wrangler.toml:

[[r2_buckets]]
binding = "IMAGES"
bucket_name = "imagebot-images"

3. Configure R2 public access or custom domain:

# Option 1: Custom domain
wrangler r2 bucket domain add imagebot-images --domain images.yourdomain.com

# Option 2: Public bucket
wrangler r2 bucket cors put imagebot-images --allow-origin '*'

4. Update r2_url generation in worker/index.ts:

const r2Url = `https://images.yourdomain.com/${r2Key}`;
// Or use R2 dev URL for testing
const r2Url = `https://imagebot-images.r2.dev/${r2Key}`;

Tailwind Styles Not Applying

Error: Components render but have no styling.

Solution:

1. Verify Tailwind config includes all content paths:

tailwind.config.mjs

export default {
  content: [
    './src/**/*.{astro,html,js,jsx,md,mdx,svelte,ts,tsx,vue}'
  ],
  // ...
}

2. Import Tailwind in layout:

src/layouts/Layout.astro

---
import '../styles/global.css';
---

3. Rebuild:

npm run build

Authentication Issues

Login Fails with Correct Password

Error:

{"error": "Invalid credentials"}

Solution:

1. Check database has user:

wrangler d1 execute imagebot-db --remote --command \
  "SELECT id, email FROM users WHERE email = 'user@example.com'"

2. Verify password was hashed during registration:

wrangler d1 execute imagebot-db --remote --command \
  "SELECT password_hash FROM users WHERE email = 'user@example.com'"
# Should be a long bcrypt hash starting with $2a$ or $2b$

3. Test bcrypt in isolation:

const bcrypt = require('bcryptjs');
const hash = await bcrypt.hash('mypassword', 10);
console.log(await bcrypt.compare('mypassword', hash)); // Should be true

Session Expires Too Quickly

Error: Logged out after a few minutes.

Solution:

Update JWT expiration in worker/index.ts:

const token = await jwt.sign({
  userId: user.id,
  exp: Math.floor(Date.now() / 1000) + (60 * 60 * 24 * 30) // 30 days instead of 7
}, env.JWT_SECRET);

Payment Issues

Stripe Webhook Fails

Error:

{"error": "Invalid signature"}

Solution:

1. Verify webhook secret:

wrangler secret list
# Should show STRIPE_WEBHOOK_SECRET

2. Test webhook signature:

const stripe = require('stripe')(process.env.STRIPE_SECRET_KEY);
const signature = request.headers.get('stripe-signature');
const event = stripe.webhooks.constructEvent(
  rawBody,
  signature,
  process.env.STRIPE_WEBHOOK_SECRET
);

3. Check Stripe Dashboard:

• Go to Developers → Webhooks
• Verify endpoint URL matches your Worker
• Check webhook logs for errors

Payment Intent Fails

Error:

{"error": "Payment failed"}

Solution:

1. Use Stripe test cards:

• Success: 4242 4242 4242 4242
• Decline: 4000 0000 0000 0002
• Requires auth: 4000 0025 0000 3155

2. Check Stripe logs:

stripe logs tail

3. Verify amount is in cents:

// Correct
amount: 999, // $9.99

// Wrong
amount: 9.99, // Invalid

Performance Issues

Slow Image Generation

Symptom: Images take 10+ seconds to generate.

Solution:

1. Use faster models:

// Fast models
'@cf/black-forest-labs/flux-1-schnell' // Fastest
'@cf/stabilityai/stable-diffusion-xl-base-1.0' // Fast

// Slower models (higher quality)
'@cf/runwayml/stable-diffusion-v1-5'

2. Reduce image size:

{
  prompt: "...",
  model: "...",
  num_steps: 4, // Lower steps = faster (min 4 for Flux)
  guidance: 7.5 // Default
}

3. Check AI model availability:

# Some models may have queue times
curl https://api.cloudflare.com/client/v4/accounts/ACCOUNT_ID/ai/models \
  -H "Authorization: Bearer API_TOKEN"

Gallery Loads Slowly

Symptom: Gallery takes long time to load with many images.

Solution:

1. Implement pagination (already in code):

// Frontend should paginate
const images = await api.get(`/api/images?limit=20&offset=${page * 20}`);

2. Enable lazy loading (already in code via react-lazy-load-image-component)

3. Optimize R2 image delivery:

• Use Cloudflare Image Resizing
• Enable CDN caching
• Compress images before upload

Rate Limiting Issues

429 Too Many Requests

Error:

{"error": "Rate limit exceeded. Try again in 60 seconds."}

Solution:

1. Implement exponential backoff:

async function retryWithBackoff(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error.status === 429 && i < maxRetries - 1) {
        await new Promise(resolve => setTimeout(resolve, 1000 * Math.pow(2, i)));
      } else {
        throw error;
      }
    }
  }
}

2. Check rate limit headers:

const response = await fetch('...');
console.log('Rate limit:', response.headers.get('X-RateLimit-Remaining'));

3. Upgrade plan or request limit increase

Development Environment Issues

Port Already in Use

Error:

Error: listen EADDRINUSE: address already in use :::4321

Solution:

# Find process using port
lsof -i :4321

# Kill process
kill -9 PID

# Or use different port
npm run dev -- --port 3000

Worker and Frontend Out of Sync

Symptom: Frontend calls API endpoint that doesn’t exist.

Solution:

1. Ensure both are running:

# Terminal 1
npm run dev

# Terminal 2
npm run worker:dev

2. Check API URL matches:

# In .env
PUBLIC_API_URL=http://localhost:8787

# Should match worker dev server port

3. Clear browser cache and reload

Production Issues

500 Internal Server Error

Error:

{"error": "Internal server error"}

Solution:

1. Check Worker logs:

wrangler tail imagebot-worker --status error

2. Review error details:

// Add better error logging in worker
try {
  // ... code
} catch (error) {
  console.error('Error details:', error);
  return new Response(JSON.stringify({
    error: 'Internal server error',
    details: error.message // Only in development
  }), { status: 500 });
}

3. Check Cloudflare dashboard:

• Workers → imagebot-worker → Metrics
• Look for error spikes and stack traces

Database Query Timeout

Error:

Error: Query exceeded time limit

Solution:

1. Add indexes:

CREATE INDEX idx_images_user_created ON images(user_id, created_at DESC);
CREATE INDEX idx_collections_user ON collections(user_id);

2. Optimize query:

-- Bad: Full table scan
SELECT * FROM images WHERE is_deleted = 0 ORDER BY created_at DESC;

-- Good: Uses index
SELECT * FROM images WHERE user_id = ? AND is_deleted = 0 ORDER BY created_at DESC LIMIT 20;

3. Use D1 analytics to find slow queries:

• Dashboard → D1 → imagebot-db → Analytics

Getting Help

If you can’t resolve an issue:

1. Check logs:

   # Worker logs
   wrangler tail imagebot-worker
   
   # Browser console
   Open DevTools → Console

2. Search GitHub issues:

   • github.com/your-org/imagebot/issues

3. Ask community:

   • Discord: discord.gg/imagebot
   • GitHub Discussions: github.com/your-org/imagebot/discussions

4. Contact support:

   • Email: support@imagebot.com
   • Include: Error message, logs, steps to reproduce

Debugging Tips

Enable Verbose Logging

worker/index.ts

const DEBUG = true;

function log(...args: any[]) {
  if (DEBUG) {
    console.log('[ImageBot]', ...args);
  }
}

// Use throughout code
log('Generating image for user:', userId);
log('Prompt:', prompt);

Test API with cURL

# Test health endpoint
curl https://imagebot-worker.workers.dev/api/health

# Test authenticated endpoint
curl https://imagebot-worker.workers.dev/api/images \
  -H "Authorization: Bearer YOUR_TOKEN"

# Test POST request
curl -X POST https://imagebot-worker.workers.dev/api/generate \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"test","model":"@cf/black-forest-labs/flux-1-schnell"}'

Browser DevTools Network Tab

1. Open DevTools → Network
2. Filter by “Fetch/XHR”
3. Click request to see:
   • Headers (including Authorization)
   • Payload
   • Response
   • Timing

Database Inspection

# List all tables
wrangler d1 execute imagebot-db --remote --command \
  "SELECT name FROM sqlite_master WHERE type='table'"

# Check table schema
wrangler d1 execute imagebot-db --remote --command \
  "PRAGMA table_info(users)"

# Sample data
wrangler d1 execute imagebot-db --remote --command \
  "SELECT * FROM images LIMIT 5"

Next Steps

• Security Best Practices
• Production Deployment
• API Reference