Troubleshooting

Troubleshooting

This page lists common issues and quick fixes to keep you moving.

Links: Quick Start Guide • Validation Scripts • Architecture Overview • Demo Scenarios

ESM module resolution issues (React SSR)

Symptom:

• 500 at /admin with message: Cannot find package 'react-dom' imported from .../rdcp-admin-app/dist/index.js

Fix (root-level SSR deps):

npm install react@18.2.0 react-dom@18.2.0 --no-save

Rationale: The Admin App dynamically imports react and react-dom/server at runtime. Installing at repo root ensures they’re resolvable in a simple non-workspace setup.

Workspace dependencies not published

Symptom:

• npm install --prefix packages/rdcp-admin-app fails with 404 for @rdcp.dev/admin-ui@0.0.0

Fix options:

• Build and use local packages:

npm run build --prefix packages/rdcp-admin-ui
npm run build --prefix packages/rdcp-admin-ui-react
npm run build --prefix packages/rdcp-admin-app

• Or install local packages from path so Node resolves them:

npm install ./packages/rdcp-core ./packages/rdcp-client ./packages/rdcp-admin-ui ./packages/rdcp-admin-ui-react

Demo ports already in use (EADDRINUSE)

Symptom:

• Error: EADDRINUSE: address already in use :::3000 or :::3100

Fix:

# Port 3000 (RDCP server)
PIDS=$(lsof -ti :3000); [ -n "$PIDS" ] && kill $PIDS
# Port 3100 (Admin App)
PIDS=$(lsof -ti :3100); [ -n "$PIDS" ] && kill $PIDS

Admin routes 404

Symptom:

• GET /admin 404 on port 3000.

Explanation: Admin UI lives in the separate Admin App on port 3100.

Fix:

• Ensure Admin App is running:

npm run start --prefix packages/rdcp-admin-app

• Access JSON endpoints:
  • http://localhost:3100/admin/spec
  • http://localhost:3100/admin/json

ESM vs CJS test failures (Jest)

Symptom:

• Errors like Unexpected token 'export' in test runs.

Status:

• Non-blocking for the demo. Runtime works. Address test infra later.

Tips for later:

• Ensure package.json exports point at actual dist outputs (import → dist/index.js if no *.esm.js is produced)
• Avoid mapping packages to raw src/ in Jest if not transforming ESM

Headless validation always works

When in doubt, run the headless data validator to differentiate runtime issues from UI issues:

RDCP_API_KEY='dev-key-change-in-production-min-32-chars' \
node --enable-source-maps scripts/validate-admin-data.mjs

Expected: AdminUISpec with groups + discovery/status with protocol: "rdcp/1.0"