Debug and Fix Issues - NaaP Docs

AI prompts to help troubleshoot errors, fix bugs, and resolve common NaaP plugin problems.

When to Use This#

Use these prompts when:

Your plugin won't start or shows errors
Something used to work but broke after a change
You see error messages you don't understand
Your plugin loads but doesn't behave correctly
Build or compilation errors

Prompt: General Debugging#

Markdown

1	# Task: Debug My NaaP Plugin
2
3	## The Problem
4
5	[DESCRIBE WHAT'S HAPPENING — for example:
6	- "My plugin shows a blank white screen when I open it"
7	- "The API call returns a 500 error"
8	- "The page loads but the data doesn't appear"
9	- "I get a TypeScript error when building"
10	]
11
12	## Error Messages
13
14	[PASTE ANY ERROR MESSAGES YOU SEE — check:
15	- Browser console (right-click → Inspect → Console tab)
16	- Terminal where you ran `naap-plugin dev`
17	- The browser's Network tab for failed API calls
18	]
19

[PASTE ERROR OUTPUT HERE]

1
2	## What I Expected
3
4	[DESCRIBE WHAT SHOULD HAPPEN]
5
6	## What I Changed Recently
7
8	[LIST ANY RECENT CHANGES — for example:
9	- "I added a new component called TaskList.tsx"
10	- "I changed the Prisma schema and ran prisma db push"
11	- "I installed a new npm package"
12	- "I didn't change anything, it just stopped working"
13	]
14
15	## Relevant Code
16
17	[PASTE THE CODE YOU THINK IS CAUSING THE ISSUE — include the full file if it's small]
18
19	## My Environment
20
21	- Node.js version: [run `node --version`]
22	- Running on: [Mac / Windows / Linux]
23	- Browser: [Chrome / Firefox / Safari]
24
25	## Please:
26
27	1. Explain what's causing the error in simple terms
28	2. Show me exactly which lines to change to fix it
29	3. Explain why the fix works
30	4. Tell me how to prevent this issue in the future

Prompt: Fix Common Errors#

Plugin Won't Load in Shell#

Markdown

1	# My NaaP Plugin Won't Load
2
3	The plugin doesn't appear in the shell sidebar, or it shows "Failed to load plugin."
4
5	Here's my plugin.json:
6	[PASTE YOUR plugin.json]
7
8	Here's my mount.tsx:
9	[PASTE YOUR mount.tsx]
10
11	Here's my vite.config.ts:
12	[PASTE YOUR vite.config.ts]
13
14	Error in browser console:
15	[PASTE ANY ERRORS]
16
17	Please check:
18	1. Is plugin.json valid and has the correct structure?
19	2. Is the mount function exported correctly?
20	3. Is the Vite UMD config correct?
21	4. Are there any missing dependencies?
22	5. Is the frontend building successfully? (check terminal output)
23
24	Show me what to fix.

API Calls Failing#

Markdown

1	# My Plugin's API Calls Are Failing
2
3	When my frontend calls the backend API, I get errors.
4
5	IMPORTANT context: NaaP deploys to Vercel. On Vercel, there are NO separate
6	backend ports — all API calls must go through the Next.js API proxy at the same
7	origin. Frontend code must NEVER hardcode `localhost:PORT` or
8	`window.location.hostname + ':PORT'`. Use `getPluginBackendUrl()` from
9	@naap/plugin-sdk which resolves correctly in both local dev and production.
10
11	Frontend code making the call:
12	[PASTE THE COMPONENT/HOOK MAKING THE API CALL]
13
14	Backend route handling the call:
15	[PASTE THE ROUTE HANDLER]
16
17	Error in browser Network tab:
18	- URL: [the failing URL]
19	- Status: [404 / 500 / CORS error / ERR_TIMED_OUT / etc.]
20	- Response body: [paste the error response]
21
22	Error in backend terminal:
23	[PASTE ANY BACKEND ERRORS]
24
25	My plugin.json backend config:
26	```json
27	{
28	"backend": {
29	"port": [PORT],
30	"apiPrefix": "/api/v1/[plugin-name]"
31	}
32	}

Please:

Check if the URL contains a hardcoded port number (common on Vercel deploys)
Show how to replace it with getPluginBackendUrl()
Diagnose and fix the issue

1
2	### Database/Prisma Errors
3
4	```markdown
5	# Prisma Database Error in My NaaP Plugin
6
7	Architecture context: NaaP uses a single PostgreSQL database (`naap`) with
8	multi-schema isolation. All models are in `packages/database/prisma/schema.prisma`.
9	Plugins import from `@naap/database`, never from `@prisma/client` or local generated dirs.
10
11	I'm getting a database error in my plugin backend.
12
13	Error message:

[PASTE THE FULL PRISMA ERROR]

1
2	My models (from packages/database/prisma/schema.prisma):
3	[PASTE THE RELEVANT MODELS]
4
5	The code that triggers the error:
6	[PASTE THE CODE MAKING THE DATABASE QUERY]
7
8	What I was trying to do:
9	[DESCRIBE THE OPERATION]
10
11	Please:
12	1. Explain what the Prisma error means
13	2. Show me the fix
14	3. Show the corrected Prisma query or schema (with @@schema annotations)
15	4. Tell me if I need to run `cd packages/database && npx prisma generate && npx prisma db push`
16	5. Verify I'm importing from @naap/database (not @prisma/client)

Build/TypeScript Errors#

Markdown

1	# Build Errors in My NaaP Plugin
2
3	When I run `npm run build` or the dev server, I get TypeScript errors.
4
5	Error output:

[PASTE THE FULL ERROR OUTPUT]

1
2	The file with the error:
3	[PASTE THE FULL FILE CONTENT]
4
5	Please:
6	1. Explain each error in simple terms
7	2. Show me the corrected code
8	3. Explain the TypeScript concept behind each fix

Vercel Deployment Failures#

Markdown

1	# My Plugin Breaks on Vercel
2
3	It works locally but fails on Vercel deployment. Common patterns:
4
5	## Build Failures
6	[PASTE THE VERCEL BUILD LOG ERROR — look for the first error line]
7
8	Known causes:
9	1. `Cannot find module 'tailwindcss'` → Delete postcss.config.js from your
10	plugin. PostCSS is configured in the shared @naap/plugin-build Vite config.
11	2. `buildCommand should NOT be longer than 256 characters` → Use bin/vercel-build.sh
12	3. `Expected ";" but found "word"` in .ts file → Check for `*/` inside JSDoc
13	comments (e.g., glob paths like `foo/*/bar` close the comment block)
14	4. `Prisma Client could not locate the Query Engine` → Check next.config.js
15	has PrismaPlugin and outputFileTracingRoot configured
16
17	## Runtime Failures (works locally, fails on Vercel)
18	[PASTE THE BROWSER CONSOLE ERRORS]
19
20	Known causes:
21	1. `ERR_TIMED_OUT` with a port number in the URL → Hardcoded localhost:PORT.
22	Fix: use getPluginBackendUrl() from @naap/plugin-sdk
23	2. `net::ERR_CONNECTION_REFUSED` → Same as above, hardcoded port
24	3. CSP violation → Update vercel.json Content-Security-Policy headers
25	4. `Database is not available` → Check DATABASE_URL env var on Vercel dashboard
26
27	Please diagnose and show the fix.

Quick Fix Reference#

Before using AI, try these common fixes:

Terminal

# Plugin not showing up? Restart the dev server

$naap-plugin dev

# Dependencies missing? Reinstall

$cd frontend && rm -rf node_modules && npm install

$cd ../backend && rm -rf node_modules && npm install

# Database out of sync? Reset from the central package

$cd packages/database

$npx prisma generate

$npx prisma db push --force-reset

# Port already in use?

$lsof -ti:4050 | xargs kill -9

# TypeScript cache stale?

$rm -rf dist tsconfig.tsbuildinfo

$npm run build

# Everything broken? Nuclear option

$rm -rf node_modules frontend/node_modules backend/node_modules

$npm install

$cd frontend && npm install

$cd ../backend && npm install

$npx prisma generate

Vercel Deployment Checklist#

Before deploying, verify your plugin passes these checks:

Terminal

# 1. No hardcoded localhost ports in frontend code

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

# Should return ZERO results (only mock/standalone dev files are ok)

# 2. No postcss.config.js in your plugin

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

# Should say "No such file or directory"

# 3. Uses shared Vite config

$grep "createPluginConfig" plugins/my-plugin/frontend/vite.config.ts

# Should match

# 4. Uses SDK for API URLs

$grep -r "getPluginBackendUrl\|usePluginApi" plugins/my-plugin/frontend/src/

# Should match wherever API calls are made

# 5. Plugin builds successfully

$cd plugins/my-plugin/frontend && npx vite build --mode production

# Should produce dist/production/*.js

Tips for Better Debugging Prompts#

Always paste the full error message — AI assistants are very good at diagnosing errors when they can see the exact output
Include the relevant code — paste the file that's causing the issue
Describe what changed — "it worked before I did X" is extremely helpful
Include your environment — Node.js version, OS, and browser matter
Be specific — "it doesn't work" is less helpful than "clicking the Save button shows a 500 error with message 'Cannot read property id of undefined'"

When to Use This#

Use these prompts when:

Your plugin won't start or shows errors
Something used to work but broke after a change
You see error messages you don't understand
Your plugin loads but doesn't behave correctly
Build or compilation errors

Prompt: General Debugging#

Markdown

1	# Task: Debug My NaaP Plugin
2
3	## The Problem
4
5	[DESCRIBE WHAT'S HAPPENING — for example:
6	- "My plugin shows a blank white screen when I open it"
7	- "The API call returns a 500 error"
8	- "The page loads but the data doesn't appear"
9	- "I get a TypeScript error when building"
10	]
11
12	## Error Messages
13
14	[PASTE ANY ERROR MESSAGES YOU SEE — check:
15	- Browser console (right-click → Inspect → Console tab)
16	- Terminal where you ran `naap-plugin dev`
17	- The browser's Network tab for failed API calls
18	]
19

[PASTE ERROR OUTPUT HERE]

1
2	## What I Expected
3
4	[DESCRIBE WHAT SHOULD HAPPEN]
5
6	## What I Changed Recently
7
8	[LIST ANY RECENT CHANGES — for example:
9	- "I added a new component called TaskList.tsx"
10	- "I changed the Prisma schema and ran prisma db push"
11	- "I installed a new npm package"
12	- "I didn't change anything, it just stopped working"
13	]
14
15	## Relevant Code
16
17	[PASTE THE CODE YOU THINK IS CAUSING THE ISSUE — include the full file if it's small]
18
19	## My Environment
20
21	- Node.js version: [run `node --version`]
22	- Running on: [Mac / Windows / Linux]
23	- Browser: [Chrome / Firefox / Safari]
24
25	## Please:
26
27	1. Explain what's causing the error in simple terms
28	2. Show me exactly which lines to change to fix it
29	3. Explain why the fix works
30	4. Tell me how to prevent this issue in the future

Prompt: Fix Common Errors#

Plugin Won't Load in Shell#

Markdown

1	# My NaaP Plugin Won't Load
2
3	The plugin doesn't appear in the shell sidebar, or it shows "Failed to load plugin."
4
5	Here's my plugin.json:
6	[PASTE YOUR plugin.json]
7
8	Here's my mount.tsx:
9	[PASTE YOUR mount.tsx]
10
11	Here's my vite.config.ts:
12	[PASTE YOUR vite.config.ts]
13
14	Error in browser console:
15	[PASTE ANY ERRORS]
16
17	Please check:
18	1. Is plugin.json valid and has the correct structure?
19	2. Is the mount function exported correctly?
20	3. Is the Vite UMD config correct?
21	4. Are there any missing dependencies?
22	5. Is the frontend building successfully? (check terminal output)
23
24	Show me what to fix.

API Calls Failing#

Markdown

1	# My Plugin's API Calls Are Failing
2
3	When my frontend calls the backend API, I get errors.
4
5	IMPORTANT context: NaaP deploys to Vercel. On Vercel, there are NO separate
6	backend ports — all API calls must go through the Next.js API proxy at the same
7	origin. Frontend code must NEVER hardcode `localhost:PORT` or
8	`window.location.hostname + ':PORT'`. Use `getPluginBackendUrl()` from
9	@naap/plugin-sdk which resolves correctly in both local dev and production.
10
11	Frontend code making the call:
12	[PASTE THE COMPONENT/HOOK MAKING THE API CALL]
13
14	Backend route handling the call:
15	[PASTE THE ROUTE HANDLER]
16
17	Error in browser Network tab:
18	- URL: [the failing URL]
19	- Status: [404 / 500 / CORS error / ERR_TIMED_OUT / etc.]
20	- Response body: [paste the error response]
21
22	Error in backend terminal:
23	[PASTE ANY BACKEND ERRORS]
24
25	My plugin.json backend config:
26	```json
27	{
28	"backend": {
29	"port": [PORT],
30	"apiPrefix": "/api/v1/[plugin-name]"
31	}
32	}

Please:

Check if the URL contains a hardcoded port number (common on Vercel deploys)
Show how to replace it with getPluginBackendUrl()
Diagnose and fix the issue

1
2	### Database/Prisma Errors
3
4	```markdown
5	# Prisma Database Error in My NaaP Plugin
6
7	Architecture context: NaaP uses a single PostgreSQL database (`naap`) with
8	multi-schema isolation. All models are in `packages/database/prisma/schema.prisma`.
9	Plugins import from `@naap/database`, never from `@prisma/client` or local generated dirs.
10
11	I'm getting a database error in my plugin backend.
12
13	Error message:

[PASTE THE FULL PRISMA ERROR]

1
2	My models (from packages/database/prisma/schema.prisma):
3	[PASTE THE RELEVANT MODELS]
4
5	The code that triggers the error:
6	[PASTE THE CODE MAKING THE DATABASE QUERY]
7
8	What I was trying to do:
9	[DESCRIBE THE OPERATION]
10
11	Please:
12	1. Explain what the Prisma error means
13	2. Show me the fix
14	3. Show the corrected Prisma query or schema (with @@schema annotations)
15	4. Tell me if I need to run `cd packages/database && npx prisma generate && npx prisma db push`
16	5. Verify I'm importing from @naap/database (not @prisma/client)

Build/TypeScript Errors#

Markdown

1	# Build Errors in My NaaP Plugin
2
3	When I run `npm run build` or the dev server, I get TypeScript errors.
4
5	Error output:

[PASTE THE FULL ERROR OUTPUT]

1
2	The file with the error:
3	[PASTE THE FULL FILE CONTENT]
4
5	Please:
6	1. Explain each error in simple terms
7	2. Show me the corrected code
8	3. Explain the TypeScript concept behind each fix

Vercel Deployment Failures#

Markdown

1	# My Plugin Breaks on Vercel
2
3	It works locally but fails on Vercel deployment. Common patterns:
4
5	## Build Failures
6	[PASTE THE VERCEL BUILD LOG ERROR — look for the first error line]
7
8	Known causes:
9	1. `Cannot find module 'tailwindcss'` → Delete postcss.config.js from your
10	plugin. PostCSS is configured in the shared @naap/plugin-build Vite config.
11	2. `buildCommand should NOT be longer than 256 characters` → Use bin/vercel-build.sh
12	3. `Expected ";" but found "word"` in .ts file → Check for `*/` inside JSDoc
13	comments (e.g., glob paths like `foo/*/bar` close the comment block)
14	4. `Prisma Client could not locate the Query Engine` → Check next.config.js
15	has PrismaPlugin and outputFileTracingRoot configured
16
17	## Runtime Failures (works locally, fails on Vercel)
18	[PASTE THE BROWSER CONSOLE ERRORS]
19
20	Known causes:
21	1. `ERR_TIMED_OUT` with a port number in the URL → Hardcoded localhost:PORT.
22	Fix: use getPluginBackendUrl() from @naap/plugin-sdk
23	2. `net::ERR_CONNECTION_REFUSED` → Same as above, hardcoded port
24	3. CSP violation → Update vercel.json Content-Security-Policy headers
25	4. `Database is not available` → Check DATABASE_URL env var on Vercel dashboard
26
27	Please diagnose and show the fix.

Quick Fix Reference#

Before using AI, try these common fixes:

Terminal

# Plugin not showing up? Restart the dev server

$naap-plugin dev

# Dependencies missing? Reinstall

$cd frontend && rm -rf node_modules && npm install

$cd ../backend && rm -rf node_modules && npm install

# Database out of sync? Reset from the central package

$cd packages/database

$npx prisma generate

$npx prisma db push --force-reset

# Port already in use?

$lsof -ti:4050 | xargs kill -9

# TypeScript cache stale?

$rm -rf dist tsconfig.tsbuildinfo

$npm run build

# Everything broken? Nuclear option

$rm -rf node_modules frontend/node_modules backend/node_modules

$npm install

$cd frontend && npm install

$cd ../backend && npm install

$npx prisma generate

Vercel Deployment Checklist#

Before deploying, verify your plugin passes these checks:

Terminal

# 1. No hardcoded localhost ports in frontend code

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

# Should return ZERO results (only mock/standalone dev files are ok)

# 2. No postcss.config.js in your plugin

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

# Should say "No such file or directory"

# 3. Uses shared Vite config

$grep "createPluginConfig" plugins/my-plugin/frontend/vite.config.ts

# Should match

# 4. Uses SDK for API URLs

$grep -r "getPluginBackendUrl\|usePluginApi" plugins/my-plugin/frontend/src/

# Should match wherever API calls are made

# 5. Plugin builds successfully

$cd plugins/my-plugin/frontend && npx vite build --mode production

# Should produce dist/production/*.js

Tips for Better Debugging Prompts#

Always paste the full error message — AI assistants are very good at diagnosing errors when they can see the exact output
Include the relevant code — paste the file that's causing the issue
Describe what changed — "it worked before I did X" is extremely helpful
Include your environment — Node.js version, OS, and browser matter
Be specific — "it doesn't work" is less helpful than "clicking the Save button shows a 500 error with message 'Cannot read property id of undefined'"