Troubleshooting

Common issues and solutions for A²D deployment, development, and usage.

Quick Fixes

Development Server Won’t Start

Problem: npm run dev fails or shows errors

Solutions:

rm -rf .next
npm run dev

rm -rf node_modules package-lock.json
npm install

node --version
# Should be 18.17+ or 20.x

# macOS/Linux
lsof -i :3000
 
# Windows
netstat -ano | findstr :3000

Database Connection Errors

Problem: “Failed to connect to database” or “Invalid API key”

Symptoms:

• Cannot sign up or log in
• API routes return 500 errors
• “Supabase client initialization failed”

Solutions:

1. Verify .env.local exists and has correct values:

   cat .env.local

2. Check Supabase project status:

   • Go to app.supabase.com
   • Verify project is not paused (free tier auto-pauses)
   • Click “Resume” if paused

3. Verify credentials:

   # Check format
   NEXT_PUBLIC_SUPABASE_URL=https://xxxxx.supabase.co
   NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJ... (starts with eyJ)
   SUPABASE_SERVICE_ROLE_KEY=eyJ... (starts with eyJ)

4. Restart development server:

   # Stop (Ctrl+C) and restart
   npm run dev

MCP Endpoint Returns 404

Problem: MCP endpoint not found or returns 404

URL Format: https://your-domain.com/api/platform/[server-id]/mcp

Solutions:

1. Verify server ID:

   • Must be valid UUID format
   • Copy from browser URL or server detail page

2. Check server exists:

   • Go to MCP Servers list
   • Verify server is created and visible

3. Ensure server is enabled:

   • Open server detail page
   • Check “Enabled” toggle is ON

4. Check deployment logs (Vercel):

   • Go to Vercel dashboard → Logs
   • Look for errors in function logs

Authentication Fails

Problem: Cannot log in or sign up, or redirects fail

Solutions:

1. Check Supabase Auth is enabled:

   • Supabase dashboard → Authentication → Providers
   • Verify “Email” provider is enabled

2. Verify redirect URLs:

   • Supabase dashboard → Authentication → URL Configuration
   • Add your app URL to allowed redirect URLs

3. Check browser console:

   • Open DevTools (F12)
   • Look for errors in Console tab

4. Clear cookies and try again:

   # Or use Incognito/Private browsing

5. Verify NEXT_PUBLIC_APP_URL:

   # Should match your actual URL
   NEXT_PUBLIC_APP_URL=http://localhost:3000  # Local
   NEXT_PUBLIC_APP_URL=https://your-domain.com  # Production

RLS Policy Errors

Problem: “Row violates row-level security policy” or “permission denied”

Symptoms:

• Cannot create/update data
• Queries return empty results unexpectedly
• “new row violates row-level security policy” error (e.g. for table agent_cards or agent_skills)

Solutions:

1. For agent_cards / agent_skills: Ensure the migration that adds RLS policies for these tables has been applied (e.g. 20260213000001_add_agent_cards_agent_skills_rls.sql). Multi-tenant migrations (e.g. organization_members, RLS helpers) must also be applied so the user has membership in an org.

2. Verify user’s organization membership: Access is based on the organization_members table, not only users.organization_id. Ensure the user has at least one row in organization_members, and that the app’s current org (stored in a cookie) matches one of those orgs. In the app, use the sidebar organization switcher if you belong to multiple orgs. For more detail, see Multi-Tenancy.

3. Check RLS policies are enabled:

   • Supabase dashboard → Table Editor
   • Select a table (including agent_cards and agent_skills)
   • Verify RLS toggle is ON

4. Logout and login again:

   • Allows the app to set the current organization cookie correctly

5. Verify using correct Supabase client:

   // ✅ Use server client in server components
   import { createClient } from '@/lib/supabase/server'
   const supabase = await createClient()
    
   // ✅ Use browser client in client components
   import { createClient } from '@/lib/supabase/client'
   const supabase = createClient()

Common Questions

How do I reset my database?

Using Supabase CLI:

supabase db reset

Manually via Dashboard:

1. Go to Supabase dashboard
2. Database → Settings
3. Click “Reset database”
4. Confirm
5. Re-run all migrations

How do I debug MCP endpoints?

Test with curl:

curl -X POST https://your-domain.com/api/platform/SERVER_ID/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'

Test with MCP Inspector:

npx @modelcontextprotocol/inspector https://your-domain.com/api/platform/SERVER_ID/mcp

Check server logs:

• Local: Check terminal running npm run dev
• Production: Vercel dashboard → Logs tab

How do I see application logs?

Local Development:

• Terminal running npm run dev
• Browser console (F12 → Console)

Production (Vercel):

1. Go to vercel.com/dashboard
2. Select your project
3. Click “Logs” tab
4. Filter by:
   • Function (API route)
   • Time range
   • Error level

How do I update environment variables?

Local:

1. Edit .env.local
2. Stop dev server (Ctrl+C)
3. Restart: npm run dev

Production (Vercel):

1. Vercel dashboard → Settings → Environment Variables
2. Edit variable
3. Redeploy (automatic on next push)

Error Reference

MCP Protocol Errors

See API Reference: Error Handling for details.

Build Errors

“Module not found”:

npm install  # Reinstall dependencies

TypeScript errors:

npm run type-check  # Check for type errors

ESLint errors:

npm run lint  # Check and auto-fix

Database Errors

“relation does not exist”:

• Migrations not run
• Run: supabase db push

“permission denied for table”:

• RLS policies not configured
• Check policies in Supabase dashboard

“connection refused”:

• Supabase project paused
• Resume project in dashboard

Getting More Help

Documentation

• Getting Started - Setup guides
• API Reference - Complete API documentation
• Architecture - System design and multi-tenancy

Community Support

• GitHub Issues: Report bugs
• GitHub Discussions: Ask questions

Detailed Troubleshooting Guides

Still stuck? Open an issue with:

• Error message
• Steps to reproduce
• Environment (local/production)
• Screenshots if applicable