Newnadoon AI Framework Troubleshooting
Last updated: Sep 4, 2026
General
- Confirm provider credentials and environment configuration.
- Check framework logs for timeout, parsing, or token-limit failures.
- Reproduce with a minimal prompt and include request IDs when escalating.
Debug dashboard
| Symptom | What to check |
|---|---|
npx newnadoon dev says the debug dashboard is not installed | @newnadoon/ai-framework is runtime only. Install npm install -D @newnadoon/ai-framework-dashboard, or use npx newnadoon-api --port 8080 if you do not need the UI. |
renderToPipeableStream is not implemented | The debugger must use Next 16.2.9 from @newnadoon/ai-framework-dashboard, not a hoisted app Next. Upgrade to @newnadoon/[email protected] and @newnadoon/[email protected]. npx newnadoon dev starts the UI from node_modules (no C:\.newnadoon-runtime copy). |
localhost:2024 shows Internal Server Error or stays on “Loading workflow structure” | Source checkouts use next dev --webpack from dashboard/. Restart after a failed compile; a first GET / 200 can still be followed by RSC 500s if two React copies are mixed. |
| Dashboard lists the wrong agents | Confirm NEWNADOON_PROJECT_DIR points at the folder that contains your newnadoon.json. |
| Start Run does nothing | The UI waits for POST /api/run to return. Prisma/Redis used to block that response. Current dashboard code registers the run in the background. If an older process is still running, restart npx newnadoon dev. Also comment POSTGRES_URL / REDIS_URL in Newnadoon-ai-framework/dashboard/.env if those services are down. |
Kanban tools say organizationId is required | In the dashboard, add organizationId to the run JSON. Do not put the ndk_ key in .env. |
MCP / Cursor
| Symptom | What to check |
|---|---|
Cursor MCP Error POSTing to endpoint (HTTP 404) / Cannot POST /api/mcp or Cannot POST /api/{%22messageEndpoint%22...} | Cursor POSTs JSON-RPC to http://localhost:8080/api/mcp. Restart npm run api after a framework rebuild so that route exists, then Reload the MCP. The SSE endpoint event must also be a raw path string. |
Browser shows Cannot GET / on localhost:8080 | That is Express’s default for a missing root route. Current newnadoon-api serves a landing page at /, or the project’s public/index.html when that file exists (@newnadoon/[email protected]+). MCP is still http://localhost:8080/api/mcp. Restart npm run api after a framework rebuild. |
GET /api/health returns 503 while the API is listening | @newnadoon/[email protected] treated a normal V8 heap as unhealthy. Use 1.0.23 or later. |
kanban-workitems is red | npx newnadoon-api or docker compose -f docker-compose.user.yml up -d must be listening on http://localhost:8080. URL is /api/mcp, not /mcp. Use @newnadoon/[email protected] or later. |
| Docker MCP cannot reach Kanban | Inside the container localhost:3001 is the container itself. Compose sets KANBAN_API_URL=http://host.docker.internal:3001 for a host Kanban. For a remote Kanban, set that URL to the public API. |
| Start Run hangs after enabling Postgres | The runs table must exist. Run npx newnadoon-db migrate deploy before newnadoon-api. Do not set POSTGRES_URL on a database that was never migrated. |
Agent runs vanish after docker compose restart api | Compose must include the postgres and redis services (not API-only). Confirm GET /api/workflows still lists the workflow id after restart. |
Voice agents (NewnaVoiceKit)
| Symptom | What to check |
|---|---|
| Voice answers, timeline empty | Set NEWNAVOICEKIT_AGENT_RUN_URL=http://localhost:2024/api/voice/turn and restart npx newnadoon-voice dev while the dashboard is running. |
| Timeline empty after a good reply | Re-select the workflow dropdown or hard-refresh. Confirm only one voice worker is running. |
| “Client runtime is not available” | Install livekit-client (npx newnadoon-voice setup) and hard-refresh. |
Worker ETIMEDOUT / cannot connect | Check NEWNAVOICEKIT_URL reaches a live media server. |
| Mic stays muted | Allow browser mic permission; click Unmute mic. |
| Greeting ignores code changes | Restart npx newnadoon-voice dev after editing createVoiceAgent. |
Full walkthrough: Voice agents.