Troubleshooting Guide

Common issues and solutions for Composter.

Installation Issues
Authentication Issues
CLI Issues
API Issues
MCP Issues
Database Issues
Frontend Issues
Performance Issues

Installation Issues

`npm install -g composter-cli` fails

Symptoms:

npm ERR! code EACCES
npm ERR! syscall access

Solution:

Option 1: Use npx (no installation)

npx composter-cli login

Option 2: Fix npm permissions

# Create directory for global packages
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'

# Add to PATH
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# Try again
npm install -g composter-cli

Option 3: Use sudo (not recommended)

sudo npm install -g composter-cli

Module not found errors

Symptoms:

Error: Cannot find module 'xyz'

Solution:

# Clear npm cache
npm cache clean --force

# Remove node_modules
rm -rf node_modules package-lock.json

# Reinstall
npm install

Authentication Issues

"Not authenticated" error

Symptoms:

Error: Not authenticated. Please run 'composter login'

Solution:

# Login again
composter login

# Check session file exists
ls -la ~/.config/composter/session.json

# If file exists but still fails, delete and re-login
rm ~/.config/composter/session.json
composter login

Session expired

Symptoms:

Error: Session expired. Please login again.

Solution:

# Sessions last 30 days, just re-login
composter login

"Invalid credentials" on login

Symptoms:

Error: Invalid email or password

Solutions:

Double-check email and password
Reset password on web dashboard: composter.vercel.app
Try creating new account if forgotten

CORS errors in browser

Symptoms:

Access to fetch at 'https://composter.onrender.com' has been blocked by CORS policy

Solutions:

For Users:

This shouldn't happen with the hosted version
Clear browser cache and cookies
Try incognito/private mode

For Self-Hosters:

# Check CLIENT_URL in api/.env matches your frontend URL
CLIENT_URL="https://your-frontend.com"

# Restart API server
cd api && npm restart

CLI Issues

Command not found: composter

Symptoms:

$ composter
command not found: composter

Solutions:

Option 1: Check installation

npm list -g composter-cli

Option 2: Use full path

# Find where npm installs global packages
npm root -g

# Use full path
~/.npm-global/bin/composter login

Option 3: Use npx

npx composter-cli login

"ECONNREFUSED" error

Symptoms:

Error: connect ECONNREFUSED 127.0.0.1:3000

Solution:

For Users:

API might be down, check status
Check internet connection

For Self-Hosters:

# Check API is running
curl http://localhost:3000/health

# Check .env file
cat cli/.env
# Should be: BASE_URL="http://localhost:3000/api"

# If using production:
# BASE_URL="https://composter.onrender.com/api"

Components not appearing after push

Symptoms: Component pushed successfully but not showing in composter ls

Solution:

# Check category exists
composter lscat

# List components in category
composter ls <category-name>

# If still missing, try pulling from web dashboard
# Go to: https://composter.vercel.app/dashboard

File not found when pushing

Symptoms:

Error: File not found: ./component.jsx

Solution:

# Check file exists
ls -la ./component.jsx

# Use absolute path
composter push buttons "Button" /full/path/to/Button.jsx

# Check current directory
pwd

API Issues

API health check fails

Symptoms:

$ curl http://localhost:3000/health
curl: (7) Failed to connect to localhost port 3000

Solution:

# Check if API is running
ps aux | grep node

# Check if port is in use
lsof -i :3000

# Start API
cd api && npm run dev

# Check logs
cd api && npm run dev 2>&1 | tee api.log

Database connection errors

Symptoms:

Error: Can't reach database server

Solution:

# Check DATABASE_URL in api/.env
cat api/.env | grep DATABASE_URL

# Test PostgreSQL connection
psql "$DATABASE_URL" -c "SELECT 1;"

# If using Neon/cloud database:
# - Check database is not paused
# - Verify connection string is correct
# - Test network connectivity

Better Auth migration errors

Symptoms:

Error: relation "user" does not exist

Solution:

cd api

# Run Prisma migrations first
npx prisma migrate dev

# Then Better Auth migrations
npx @better-auth/cli migrate

# Verify tables exist
psql "$DATABASE_URL" -c "\dt"

Port already in use

Symptoms:

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

Solution:

# Find process using port
lsof -i :3000

# Kill the process
kill -9 <PID>

# Or use different port in api/.env
PORT=3001

MCP Issues

AI assistant doesn't recognize Composter

Symptoms: AI responds with "I don't have access to Composter" or doesn't use MCP tools

Solutions:

Verify config file exists:

# Claude Desktop (macOS)
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Cursor
cat .cursor/mcp.json

# VS Code
cat .vscode/mcp.json

Validate JSON syntax:
```
# Use jq to check
cat mcp.json | jq .
```
Restart AI assistant completely:
- Quit the application (don't just close window)
- Reopen

Check logs:

# Claude Desktop logs
tail -f ~/Library/Logs/Claude/mcp*.log

"Composter MCP server not found"

Symptoms:

Error: MCP server 'composter' failed to start

Solution:

# Check composter-mcp is installed
npm list -g composter-mcp

# Install if missing
npm install -g composter-mcp

# Verify npx can find it
npx composter-mcp --version

# Test MCP server manually
npx composter-mcp

MCP authentication fails

Symptoms:

Error: Authentication failed - no valid session found

Solution:

# Login via CLI first
composter login

# Verify session exists
cat ~/.config/composter/session.json

# Check session hasn't expired
# Sessions last 30 days

# Re-login if needed
rm ~/.config/composter/session.json
composter login

MCP returns empty results

Symptoms: AI says "You don't have any categories" but you know you do

Solution:

# Verify via CLI first
composter lscat

# Check session is valid
composter ls

# If CLI works but MCP doesn't:
# 1. Restart AI assistant
# 2. Re-run MCP init
npx composter-mcp init claude  # or cursor/vscode/windsurf

# 3. Check MCP logs for errors

Database Issues

Prisma migration errors

Symptoms:

Error: Migration failed to apply

Solution:

cd api

# Reset database (WARNING: deletes all data)
npx prisma migrate reset

# Or apply migrations incrementally
npx prisma migrate deploy

# If migrations are out of sync:
npx prisma migrate resolve --applied <migration_name>

"relation already exists"

Symptoms:

Error: relation "Category" already exists

Solution:

# Check migration status
npx prisma migrate status

# If migrations are applied but Prisma thinks they're not:
npx prisma migrate resolve --applied <migration_name>

# Or start fresh (WARNING: deletes data)
npx prisma migrate reset

Database locked

Symptoms:

Error: database is locked

Solution:

# Close all connections to database
# Kill any running API processes
pkill -f "node.*api"

# Restart PostgreSQL
sudo systemctl restart postgresql

# Try migration again
npx prisma migrate dev

Frontend Issues

Blank page after deployment

Symptoms: Frontend shows blank page, no errors

Solution:

# Check browser console (F12)
# Look for errors

# Common issue: API URL incorrect
# Check frontend/.env
VITE_API_URL="https://your-api.com"

# Rebuild
npm run build

# Check build output
ls -la dist/

Components not loading

Symptoms: Dashboard shows "No components found" but they exist

Solution:

# Check network tab (F12) for API errors
# Verify API is accessible

# Test API directly
curl https://your-api.com/api/categories \
  -H "Authorization: Bearer YOUR_TOKEN"

# Check CORS configuration in api/.env
CLIENT_URL="https://your-frontend.com"

Build failures

Symptoms:

npm run build failed

Solution:

# Clear cache
rm -rf node_modules .vite

# Reinstall
npm install

# Check Node version (needs 18+)
node --version

# Try building with verbose output
npm run build -- --debug

Performance Issues

Slow API responses

Symptoms: API calls take >5 seconds

Solutions:

Check database connection latency:

# If using cloud database, test ping
ping your-database.com

Enable database joins in Better Auth:

// api/auth/auth.js
export const auth = betterAuth({
  experimental: { joins: true }
});

Add database indexes:

CREATE INDEX idx_component_category ON "Component"("category");
CREATE INDEX idx_component_user ON "Component"("userId");

Use connection pooling:

// api/prisma.js
const prisma = new PrismaClient({
  datasources: {
    db: {
      url: process.env.DATABASE_URL + "?connection_limit=10"
    }
  }
});

High memory usage

Symptoms: API process using excessive RAM

Solution:

# Monitor memory
top -p $(pgrep -f "node.*api")

# Restart API regularly (use PM2)
pm2 restart composter-api

# Adjust Node memory limit
NODE_OPTIONS="--max-old-space-size=512" npm start

Frontend slow to load

Symptoms: Initial page load takes >10 seconds

Solutions:

Enable production build:

npm run build
npm run preview  # Don't use 'dev' in production

Check bundle size:

npm run build -- --stats
# Analyze build/stats.html

Use CDN for assets (if self-hosting)

Getting More Help

If these solutions don't help:

Check GitHub Issues: github.com/binit2-1/Composter/issues
Search Discussions: github.com/binit2-1/Composter/discussions
Open New Issue:
- Include error messages
- Describe steps to reproduce
- Mention your environment (OS, Node version, etc.)
- Share relevant logs

Check Logs:

# API logs
cd api && npm run dev 2>&1 | tee debug.log

# MCP logs
tail -f ~/.composter/mcp.log

# System logs
journalctl -u composter-api -n 100

Debug Mode

Enable verbose logging for troubleshooting:

CLI:

export DEBUG=composter:*
composter login

API:

export DEBUG=*
cd api && npm run dev

MCP:

{
  "mcpServers": {
    "composter": {
      "command": "npx",
      "args": ["composter-mcp"],
      "env": {
        "DEBUG": "composter:*"
      }
    }
  }
}

FilesExpand file tree

troubleshooting.md

Latest commit

History

troubleshooting.md

File metadata and controls

Troubleshooting Guide

Table of Contents

Installation Issues

npm install -g composter-cli fails

Module not found errors

Authentication Issues

"Not authenticated" error

Session expired

"Invalid credentials" on login

CORS errors in browser

CLI Issues

Command not found: composter

"ECONNREFUSED" error

Components not appearing after push

File not found when pushing

API Issues

API health check fails

Database connection errors

Better Auth migration errors

Port already in use

MCP Issues

AI assistant doesn't recognize Composter

"Composter MCP server not found"

MCP authentication fails

MCP returns empty results

Database Issues

Prisma migration errors

"relation already exists"

Database locked

Frontend Issues

Blank page after deployment

Components not loading

Build failures

Performance Issues

Slow API responses

High memory usage

Frontend slow to load

Getting More Help

Debug Mode

See Also

`npm install -g composter-cli` fails