Troubleshooting

Solutions for common issues when developing with the NaaP platform.

Quick Diagnostics#

Run these commands to quickly identify issues:

Terminal

# Check all service health

$./bin/start.sh validate

# Check running services

$./bin/start.sh status

# Check Docker containers

$docker ps | grep naap

Startup Failures#

Base Service Won't Start#

Symptom: base-svc failed to start on port 4000

Common causes:

Database not running:

Terminal

$docker ps | grep naap-db

# If not running:

$docker start naap-db

# Or re-create:

$./bin/start.sh

Port 4000 already in use:

Terminal

$lsof -i :4000

$kill <PID>

$./bin/start.sh

Missing .env file:

Terminal

# Auto-creates all missing .env files

$./bin/start.sh # ensure_env_files runs automatically

Shell Won't Start#

Symptom: Shell failed to start on port 3000

Missing .env.local:

Terminal

# Check if it exists

$ls apps/web-next/.env.local

# If missing, re-run start (setup is automatic)

$./bin/start.sh

Port 3000 in use:

Terminal

$lsof -i :3000

$kill <PID>

Node modules corrupted:

Terminal

$rm -rf node_modules

$npm install

Plugin Not Loading in Browser#

Symptom: Plugin shows as grey/disabled or errors in console

Check CDN bundle exists:

Terminal

$curl -sf http://localhost:3000/cdn/plugins/<plugin-name>/1.0.0/<plugin-name>.js | head -1

Rebuild the plugin:

Terminal

$cd plugins/<plugin-name>/frontend

$npm run build

Check plugin is registered:

Terminal

$curl -sf http://localhost:4000/api/v1/base/plugins | python3 -m json.tool

Database Issues#

Connection Refused#

Symptom: ECONNREFUSED 127.0.0.1:5432

Terminal

# Check if Docker is running

$docker info

# Check if naap-db container exists

$docker ps -a | grep naap-db

# Start it

$docker start naap-db

# Or recreate from scratch

$docker rm -f naap-db

$./bin/start.sh

Schema Missing Tables#

Symptom: validate shows schema exists but no tables

Terminal

# Push the unified Prisma schema

$cd packages/database

$DATABASE_URL="postgresql://postgres:postgres@localhost:5432/naap" npx prisma db push

Prisma Client Not Generated#

Symptom: Cannot find module './generated/client/index.js'

Terminal

$cd packages/database

$npx prisma generate

Build Issues#

Plugin Build Fails#

Terminal

# Check the build log

$cat logs/<plugin-name>-build.log

# Try building manually with verbose output

$cd plugins/<plugin-name>/frontend

$npx vite build --mode production

TypeScript Errors#

Terminal

# Check types across the monorepo

$npx tsc --noEmit

# Check a specific package

$cd packages/plugin-sdk

$npx tsc --noEmit

Network/Port Issues#

Default Port Assignments#

Service	Port
Next.js Shell	3000
Plugin Server	3100
Base Service	4000
Gateway Manager	4001
Orchestrator Manager	4002
Capacity Planner	4003
Network Analytics	4004
Marketplace	4005
Community	4006
My Wallet	4007
My Dashboard	4008
Daydream Video	4010
Developer API	4011
Plugin Publisher	4012
PostgreSQL	5432

Kill All NaaP Processes#

Terminal

$./bin/stop.sh

# If that doesn't work:

$pkill -f "next dev" 2>/dev/null

$pkill -f "tsx watch" 2>/dev/null

Environment Issues#

Missing .env Files After Clone#

The .env files are gitignored for security. They're auto-created by:

Terminal

# Auto-creates all missing .env files

$./bin/start.sh # Creates on every startup

# Setup runs automatically on first start

Wrong Database URL in .env#

Terminal

# Check what's configured

$grep DATABASE_URL plugins/*/backend/.env

# All should point to:

# postgresql://postgres:postgres@localhost:5432/naap?schema=plugin_<name>

Performance#

Slow Next.js Startup#

First startup compiles all pages. Subsequent starts are faster due to .next cache.

Terminal

# Clear Next.js cache if needed

$rm -rf apps/web-next/.next

Slow Plugin Builds#

Terminal

# Build plugins in parallel

$npm run build:plugins

Vercel Deployment Issues#

Plugin API Calls Timeout on Vercel#

Symptom: GET https://naap-....vercel.app:4006/api/v1/community/posts net::ERR_TIMED_OUT

Cause: Hardcoded localhost:PORT or window.location.hostname + ':PORT' in frontend code. On Vercel, there are no backend microservices — only the Next.js API proxy on port 443.

Fix: Use getPluginBackendUrl() from @naap/plugin-sdk:

TypeScript

1	// WRONG
2	const API_BASE = 'http://localhost:4006/api/v1/community';
3	const API_BASE = `${window.location.hostname}:4006/api/v1/community`;
4
5	// CORRECT
6	import { getPluginBackendUrl } from '@naap/plugin-sdk';
7	const API_BASE = getPluginBackendUrl('community', {
8	apiPath: '/api/v1/community',
9	});

Search your plugin for hardcoded ports:

Terminal

# Find hardcoded localhost ports in frontend code

$grep -r "localhost:[0-9]" plugins/my-plugin/frontend/src/

$grep -r "location\.hostname.*:[0-9]" plugins/my-plugin/frontend/src/

Cannot Find Module 'tailwindcss' on Vercel#

Symptom: Loading PostCSS Plugin failed: Cannot find module 'tailwindcss'

Cause: A postcss.config.js exists in your plugin's frontend/ directory. On Vercel, PostCSS tries to require('tailwindcss') from the plugin directory, where hoisted dependencies aren't reachable.

Fix: Delete your plugin's postcss.config.js. PostCSS is configured centrally in @naap/plugin-build's shared Vite config:

Terminal

# Remove if it exists

$rm plugins/my-plugin/frontend/postcss.config.js

# Keep your tailwind.config.js — that's fine

$ls plugins/my-plugin/frontend/tailwind.config.js

Vercel buildCommand Too Long#

Symptom: buildCommand should NOT be longer than 256 characters

Cause: Complex multi-step build commands in vercel.json.

Fix: Use bin/vercel-build.sh as the build command. All build steps are in this script.

Prisma Query Engine Not Found on Vercel#

Symptom: Prisma Client could not locate the Query Engine for runtime "rhel-openssl-3.0.x"

Fix: Ensure next.config.js includes:

JavaScript

1	const { PrismaPlugin } = require('@prisma/nextjs-monorepo-workaround-plugin');
2
3	module.exports = {
4	output: 'standalone',
5	outputFileTracingRoot: path.join(__dirname, '../../'),
6	webpack: (config) => {
7	config.plugins.push(new PrismaPlugin());
8	return config;
9	},
10	};

JSDoc Comment Breaks esbuild#

Symptom: Expected ";" but found "some_word" during npx tsx execution

Cause: A JSDoc comment contains */ (e.g., in a glob path like plugins/*/plugin.json), which prematurely closes the comment block.

Fix: Avoid */ in comments. Use {name} or spell it out:

TypeScript

1	// WRONG — the */ closes the comment!
2	/** Discovers plugins from plugins//plugin.json /
3
4	// CORRECT
5	/** Discovers plugins from plugins/{name}/plugin.json */

Getting Help#

Run ./bin/start.sh validate for a comprehensive health check
Check logs: ./bin/start.sh logs <service>
Check the Architecture docs for understanding
File an issue on GitHub

Quick Diagnostics#

Run these commands to quickly identify issues:

Terminal

# Check all service health

$./bin/start.sh validate

# Check running services

$./bin/start.sh status

# Check Docker containers

$docker ps | grep naap

Startup Failures#

Base Service Won't Start#

Symptom: base-svc failed to start on port 4000

Common causes:

Database not running:

Terminal

$docker ps | grep naap-db

# If not running:

$docker start naap-db

# Or re-create:

$./bin/start.sh

Port 4000 already in use:

Terminal

$lsof -i :4000

$kill <PID>

$./bin/start.sh

Missing .env file:

Terminal

# Auto-creates all missing .env files

$./bin/start.sh # ensure_env_files runs automatically

Shell Won't Start#

Symptom: Shell failed to start on port 3000

Missing .env.local:

Terminal

# Check if it exists

$ls apps/web-next/.env.local

# If missing, re-run start (setup is automatic)

$./bin/start.sh

Port 3000 in use:

Terminal

$lsof -i :3000

$kill <PID>

Node modules corrupted:

Terminal

$rm -rf node_modules

$npm install

Plugin Not Loading in Browser#

Symptom: Plugin shows as grey/disabled or errors in console

Check CDN bundle exists:

Terminal

$curl -sf http://localhost:3000/cdn/plugins/<plugin-name>/1.0.0/<plugin-name>.js | head -1

Rebuild the plugin:

Terminal

$cd plugins/<plugin-name>/frontend

$npm run build

Check plugin is registered:

Terminal

$curl -sf http://localhost:4000/api/v1/base/plugins | python3 -m json.tool

Database Issues#

Connection Refused#

Symptom: ECONNREFUSED 127.0.0.1:5432

Terminal

# Check if Docker is running

$docker info

# Check if naap-db container exists

$docker ps -a | grep naap-db

# Start it

$docker start naap-db

# Or recreate from scratch

$docker rm -f naap-db

$./bin/start.sh

Schema Missing Tables#

Symptom: validate shows schema exists but no tables

Terminal

# Push the unified Prisma schema

$cd packages/database

$DATABASE_URL="postgresql://postgres:postgres@localhost:5432/naap" npx prisma db push

Prisma Client Not Generated#

Symptom: Cannot find module './generated/client/index.js'

Terminal

$cd packages/database

$npx prisma generate

Build Issues#

Plugin Build Fails#

Terminal

# Check the build log

$cat logs/<plugin-name>-build.log

# Try building manually with verbose output

$cd plugins/<plugin-name>/frontend

$npx vite build --mode production

TypeScript Errors#

Terminal

# Check types across the monorepo

$npx tsc --noEmit

# Check a specific package

$cd packages/plugin-sdk

$npx tsc --noEmit

Network/Port Issues#

Default Port Assignments#

Service	Port
Next.js Shell	3000
Plugin Server	3100
Base Service	4000
Gateway Manager	4001
Orchestrator Manager	4002
Capacity Planner	4003
Network Analytics	4004
Marketplace	4005
Community	4006
My Wallet	4007
My Dashboard	4008
Daydream Video	4010
Developer API	4011
Plugin Publisher	4012
PostgreSQL	5432

Kill All NaaP Processes#

Terminal

$./bin/stop.sh

# If that doesn't work:

$pkill -f "next dev" 2>/dev/null

$pkill -f "tsx watch" 2>/dev/null

Environment Issues#

Missing .env Files After Clone#

The .env files are gitignored for security. They're auto-created by:

Terminal

# Auto-creates all missing .env files

$./bin/start.sh # Creates on every startup

# Setup runs automatically on first start

Wrong Database URL in .env#

Terminal

# Check what's configured

$grep DATABASE_URL plugins/*/backend/.env

# All should point to:

# postgresql://postgres:postgres@localhost:5432/naap?schema=plugin_<name>

Performance#

Slow Next.js Startup#

First startup compiles all pages. Subsequent starts are faster due to .next cache.

Terminal

# Clear Next.js cache if needed

$rm -rf apps/web-next/.next

Slow Plugin Builds#

Terminal

# Build plugins in parallel

$npm run build:plugins

Vercel Deployment Issues#

Plugin API Calls Timeout on Vercel#

Symptom: GET https://naap-....vercel.app:4006/api/v1/community/posts net::ERR_TIMED_OUT

Cause: Hardcoded localhost:PORT or window.location.hostname + ':PORT' in frontend code. On Vercel, there are no backend microservices — only the Next.js API proxy on port 443.

Fix: Use getPluginBackendUrl() from @naap/plugin-sdk:

TypeScript

1	// WRONG
2	const API_BASE = 'http://localhost:4006/api/v1/community';
3	const API_BASE = `${window.location.hostname}:4006/api/v1/community`;
4
5	// CORRECT
6	import { getPluginBackendUrl } from '@naap/plugin-sdk';
7	const API_BASE = getPluginBackendUrl('community', {
8	apiPath: '/api/v1/community',
9	});

Search your plugin for hardcoded ports:

Terminal

# Find hardcoded localhost ports in frontend code

$grep -r "localhost:[0-9]" plugins/my-plugin/frontend/src/

$grep -r "location\.hostname.*:[0-9]" plugins/my-plugin/frontend/src/

Cannot Find Module 'tailwindcss' on Vercel#

Symptom: Loading PostCSS Plugin failed: Cannot find module 'tailwindcss'

Fix: Delete your plugin's postcss.config.js. PostCSS is configured centrally in @naap/plugin-build's shared Vite config:

Terminal

# Remove if it exists

$rm plugins/my-plugin/frontend/postcss.config.js

# Keep your tailwind.config.js — that's fine

$ls plugins/my-plugin/frontend/tailwind.config.js

Vercel buildCommand Too Long#

Symptom: buildCommand should NOT be longer than 256 characters

Cause: Complex multi-step build commands in vercel.json.

Fix: Use bin/vercel-build.sh as the build command. All build steps are in this script.

Prisma Query Engine Not Found on Vercel#

Symptom: Prisma Client could not locate the Query Engine for runtime "rhel-openssl-3.0.x"

Fix: Ensure next.config.js includes:

JavaScript

1	const { PrismaPlugin } = require('@prisma/nextjs-monorepo-workaround-plugin');
2
3	module.exports = {
4	output: 'standalone',
5	outputFileTracingRoot: path.join(__dirname, '../../'),
6	webpack: (config) => {
7	config.plugins.push(new PrismaPlugin());
8	return config;
9	},
10	};

JSDoc Comment Breaks esbuild#

Symptom: Expected ";" but found "some_word" during npx tsx execution

Cause: A JSDoc comment contains */ (e.g., in a glob path like plugins/*/plugin.json), which prematurely closes the comment block.

Fix: Avoid */ in comments. Use {name} or spell it out:

TypeScript

1	// WRONG — the */ closes the comment!
2	/** Discovers plugins from plugins//plugin.json /
3
4	// CORRECT
5	/** Discovers plugins from plugins/{name}/plugin.json */

Getting Help#

Run ./bin/start.sh validate for a comprehensive health check
Check logs: ./bin/start.sh logs <service>
Check the Architecture docs for understanding
File an issue on GitHub