Troubleshooting

Solutions to common issues you might encounter when working with Modello products.

Common Issues

Here are the most common issues users encounter and their solutions:

Installation Problems

"npm install" fails with permission errors

Solution:

# Fix npm permissions (macOS/Linux)
sudo chown -R $(whoami) ~/.npm
sudo chown -R $(whoami) /usr/local/lib/node_modules

# Or use a Node version manager like nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install node
nvm use node

"Module not found" errors after installation

Solution:

# Clear cache and reinstall
rm -rf node_modules package-lock.json
npm cache clean --force
npm install

# For yarn users
rm -rf node_modules yarn.lock
yarn cache clean
yarn install

Node.js version compatibility issues

Solution:

# Check your Node.js version
node --version

# Modello products require Node.js 18.17.0 or higher
# Update Node.js if needed
nvm install 18.17.0
nvm use 18.17.0

# Or download from nodejs.org

Development Server Issues

Port 3000 already in use

Solution:

# Use a different port
npm run dev -- -p 3001

# Or kill the process using port 3000
# On macOS/Linux:
lsof -ti:3000 | xargs kill -9

# On Windows:
netstat -ano | findstr :3000
taskkill /PID <PID_NUMBER> /F

Hot reload not working

Solution:

Restart the development server
Clear browser cache (Ctrl+Shift+R or Cmd+Shift+R)
Check if files are being watched correctly
Disable browser extensions that might interfere

Styles not loading or updating

Solution:

# Restart development server
npm run dev

# Clear Tailwind cache
rm -rf .next
npm run dev

# Check if Tailwind config is correct
npx tailwindcss -i ./app/globals.css -o ./output.css --watch

Database Connection

"Connection refused" or "Connection timeout"

Solution:

Verify DATABASE_URL in your .env.local file
Check if your database service is running
Ensure firewall allows database connections
For Neon: Check if your database is in sleep mode

SSL connection errors

Solution:

# Ensure your DATABASE_URL includes SSL mode
DATABASE_URL="postgresql://user:pass@host:5432/db?sslmode=require"

# For development, you might need to disable SSL
DATABASE_URL="postgresql://user:pass@localhost:5432/db?sslmode=disable"

"Table doesn't exist" errors

Solution:

# Run database migrations (if using Prisma)
npx prisma migrate dev

# Or generate and push schema
npx prisma db push

# Seed the database if needed
npm run db:seed

Deployment Issues

Common problems encountered during deployment and their solutions:

Build Failures

TypeScript compilation errors

Solution:

# Check for TypeScript errors locally
npm run type-check

# Fix common issues:
# 1. Missing type definitions
npm install @types/node @types/react @types/react-dom

# 2. Update TypeScript configuration
# Check tsconfig.json for correct settings

"Module not found" during build

Solution:

Ensure all dependencies are in package.json
Check import paths are correct (case-sensitive)
Verify file extensions are included where needed
Check if files exist in the repository

Out of memory errors during build

Solution:

# Increase Node.js memory limit
NODE_OPTIONS="--max-old-space-size=4096" npm run build

# Or add to package.json scripts:
"build": "NODE_OPTIONS='--max-old-space-size=4096' next build"

Environment Variables

Environment variables not working in production

Solution:

Ensure variables are set in your deployment platform
Client-side variables must be prefixed with NEXT_PUBLIC_
Restart your deployment after adding variables
Check variable names match exactly (case-sensitive)

Database connection fails in production

Solution:

# Ensure production DATABASE_URL includes SSL
DATABASE_URL="postgresql://user:pass@host:5432/db?sslmode=require"

# For Neon, use the pooled connection string
POSTGRES_PRISMA_URL="postgresql://user:pass@host:5432/db?sslmode=require&pgbouncer=true"

Domain & SSL Issues

Custom domain not working

Solution:

Wait up to 48 hours for DNS propagation
Check DNS records are configured correctly
Use DNS checker tools to verify propagation
Clear browser cache and try incognito mode

SSL certificate errors

Solution:

SSL certificates are typically automatic on hosting platforms
Wait for certificate provisioning (can take up to 24 hours)
Ensure domain is properly verified
Contact platform support if issues persist

Performance Optimization

Solutions for common performance issues:

Slow Loading Times

Images loading slowly

Solution:

// Use Next.js Image component with optimization
import Image from "next/image"

<Image
  src="/images/hero.jpg"
  alt="Hero image"
  width={1920}
  height={1080}
  priority // For above-the-fold images
  placeholder="blur" // Add blur placeholder
  blurDataURL="data:image/jpeg;base64,..." // Base64 blur
/>

Database queries taking too long

Solution:

Add database indexes for frequently queried columns
Use connection pooling (Neon provides this automatically)
Implement caching for repeated queries
Optimize query structure and reduce N+1 queries

Large Bundle Size

Bundle size too large

Solution:

// Use dynamic imports for heavy components
import dynamic from 'next/dynamic'

const HeavyComponent = dynamic(() => import('./HeavyComponent'), {
  loading: () => <p>Loading...</p>,
})

// Tree-shake unused imports
import { specificFunction } from 'library' // Good
import * as library from 'library' // Avoid this

Analyze bundle size

Solution:

# Install bundle analyzer
npm install --save-dev @next/bundle-analyzer

# Add to next.config.mjs
const withBundleAnalyzer = require('@next/bundle-analyzer')({
  enabled: process.env.ANALYZE === 'true',
})

# Analyze bundle
ANALYZE=true npm run build

Getting Additional Help

Before Contacting Support

To help us assist you faster, please include:

Product name and version
Error messages (full text)
Steps to reproduce the issue
Your development environment details

Contact Support Browse FAQ

Still stuck? Our support team is here to help you get back on track.