05 — designer-api: where to look
A symptom → location routing table.
Server won't boot
| Symptom |
First place to look |
Cannot find module '...' |
package.json; re-run yarn install; Node 20.x |
Something Went Wrong! |
MySQL unreachable — check host/user/password/database env vars |
EADDRINUSE :::5002 |
Port collision with someli-api or Someli-admin-api. Set port=5003 in .env. |
| Native build error (Sharp, Puppeteer) |
Missing system packages — ../00-workstation-setup.md §2 |
Auth issues
| Symptom |
First place to look |
| 401 / 403 |
helper/index.js for the auth helper; the inline auth check in the specific routes/routes.js handler |
| Designer FE login fails |
The login endpoint inside routes/routes.js — find by grepping for the URL the FE calls |
| Reference |
../../audit/designer-api/authentication.md |
A specific endpoint is broken
| Where to look |
When |
routes/routes.js |
All 269 endpoints are here. Search for the path string. |
actions/actions.js |
If the endpoint uses the generic CRUD wrapper |
helper/index.js |
If the endpoint imports a helper function |
| Endpoint inventory |
../../audit/designer-api/API-inventory.md |
A job didn't run
| Symptom |
First place to look |
| Scheduled job didn't fire |
cron.schedule(...) line in the job file — verify the cron expression |
| Job fires but does nothing |
The handler's first SQL query — usually SELECT WHERE due/pending — check the data is actually there |
| Industry-clone behaves differently from siblings |
These files have drifted manually over time; diff side-by-side |
| Jobs inventory |
../../audit/designer-api/jobs-inventory.md |
| Bots inventory |
../../audit/designer-api/bots-inventory.md |
AI content generation issues
| Symptom |
First place to look |
| OpenAI 401 |
OPENAI_API_KEY env var |
| OpenAI 429 (rate limit) |
Multiple bots or jobs hitting OpenAI simultaneously — check schedules |
| Generated content empty |
The bot's prompt + the OpenAI response — console.log temporarily and re-run |
| Reference |
../../audit/designer-api/content-pipeline.md |
| Symptom |
First place to look |
| Polotno image render fails |
polotno_image_uploader.js + Polotno-related endpoints in routes/routes.js |
| Upload to S3 fails |
AWS env vars; s3_Image_upload.js |
| Stock images don't appear |
PEXELS_API_KEY, PIXABAY_API_KEY |
| Reference |
../../audit/designer-api/media-processing.md |
Notifications
| Symptom |
First place to look |
| Slack / Teams notification missing |
teamsnotification.js — the (hardcoded — known finding) token / channel |
| Email not sent |
SENDGRID_API_KEY, FROM env vars |
| Reference |
../../audit/designer-api/notifications.md |
Deployment issues
| Symptom |
First place to look |
| Deploy doesn't reflect your change |
No in-repo CI exists — ask the team how deploy is triggered |
.env baked into Docker image |
Known finding — Dockerfile does COPY .env conf.js favicon.ico ./ |
| PM2 process status unclear |
No ecosystem.config.js in repo; PM2 is managed outside |
| Reference |
../../audit/designer-api/build-and-deploy.md |
Cross-repo / shared-DB issues
| Symptom |
First place to look |
Job behaves differently when someli-api is running |
They share MySQL — concurrent writes are possible |
A schema change in someli-api breaks a designer job |
The job assumed a column / type that no longer exists |
| FE expects a column the job hasn't populated |
Job order matters — content factory has to finish before customer FE renders |
| Reference |
../../audit/CODE-OVERLAP-MATRIX.md, ../../audit/designer-api/code-overlap.md |
Error-handling / unexpected errors
| Symptom |
First place to look |
| Express error handler returns generic 500 |
There is no global error middleware — uncaught throws crash the process |
| Job crashes silently and stops |
Unhandled promise rejection inside the cron handler; wrap in try/catch |
| Reference |
../../audit/designer-api/error-handling.md |
When all else fails