05 — someli-api: where to look
A symptom → location routing table. Use this when something is broken and you don't know where to start.
Server won't boot
| Symptom in log |
First place to look |
Cannot find module '...' |
package.json deps; re-run yarn install; ensure Node 20.x |
Something Went Wrong! |
modules/dbDriver/lib/mysql.js — MySQL unreachable. Check host/user/password/database env vars. |
EADDRINUSE :::5002 |
Another backend is already on 5002 (designer-api or Someli-admin-api default to the same port). Change port in .env. |
Crash referencing JWT_SECRET_KEY |
Set JWT_SECRET_KEY and TOKEN_HEADER_KEY in .env |
| Sharp / native-build error |
Missing system packages — 00-workstation-setup.md §2 |
Auth issues
| Symptom |
First place to look |
| 401 on every request |
Is the Token header set? (Header name = TOKEN_HEADER_KEY env var) |
| 401 sometimes only |
Token expired or revoked. Token revocation lives in helper/revokeToken.js — in-memory, clears on restart. |
| OAuth callback fails |
middlewares/passport.js (the specific strategy), then the callback handler in routes/social.js |
| "Account does not belong to user" |
checkuseraccount(userId, accountId) is failing — check tMember_Account (or equivalent) rows |
| Partner API request fails |
routes/partnerAuth.js — uses its own JWT, not the main token format |
| Reference |
../../audit/someli-api/authentication.md |
A specific endpoint is broken
| Where to look |
When |
routes/routes.js |
The endpoint is mounted at the root (e.g., /myEndpoint). Search for the path string. |
routes/auth.js |
The path starts with /auth/. |
routes/social.js |
OAuth handshake (path starts with /social/). |
routes/paddle.js |
Paddle billing (path starts with /paddle/). |
routes/partnerAuth.js |
Partner API (path starts with /partnerAuth/). |
dashboard/routes/index.js |
Analytics / leaderboards (path starts with /auth but the dashboard module also lives there). |
| Endpoint inventory |
../../audit/someli-api/API-inventory.md |
Tip: the route files are huge. grep -n '/myEndpoint' routes/ from the repo root narrows down fast.
A scheduled publish failed
| Where to look |
When |
job_facebook_publish.js |
Facebook publishing |
job_instagram_publish.js |
Instagram |
job_linkedin_publish.js |
LinkedIn |
job_tiktok_publish.js |
TikTok |
job_twitter_publish.js / job_x_publish.js |
X (Twitter) |
tPost table status column |
Post status — scheduled / publishing / published / failed |
| Token refresh jobs |
If publishing fails with auth error, the access token may have expired — look for the corresponding job_*_refresh.js |
| Jobs inventory |
../../audit/someli-api/jobs-inventory.md |
AI content generation issues
| Symptom |
Where to look |
| Bedrock errors |
helper/aiLogics.js — model routing; AWS_BEDROCK_* env vars |
| Vertex / Gemini errors |
helper/aiLogics.js, conf/credentials.json, GOOGLE_API_KEY |
| OpenAI errors |
OPENAI_API_KEY; usage scattered through routes and jobs |
| Agent flow misbehaves |
agents/<name>Agent.js; trace the multi-step calls |
| Reference |
../../audit/someli-api/agents-and-ai.md, ../../audit/someli-api/content-pipeline.md |
RAG / knowledge-base issues
| Symptom |
Where to look |
| Customer says "the AI doesn't know my brand info" |
helper/ragProcess.js, look for the per-account corpus |
| RAG sync stuck |
job_rag_*.js files; check tRAG* tables |
| Vertex errors |
CLOUD_PROJECT_ID, CLOUD_LOCATION, CLOUD_BUCKET_NAME, conf/credentials.json |
| Reference |
../../audit/someli-api/rag-pipeline.md |
Payment / billing issues
| Symptom |
Where to look |
| Paddle webhook 4xx in logs |
routes/routes.js — find paddle_*_webhooks handlers. Signature verification needs raw body — confirm server.js middleware ordering is intact. |
| Customer charged but no plan upgrade |
tSubscription / tAccount updates inside the webhook handler |
| Stripe webhook (legacy) |
routes/routes.js — /stripe_webhooks |
| Sandbox vs prod confusion |
PADDLE_ENV / PADDLE_TEST_ENV env vars; sandbox keys are different |
| Reference |
../../audit/someli-api/API-inventory.md § paddle / stripe |
| Symptom |
Where to look |
| Generated image broken |
Polotno call chain in helper/aiLogics.js or image-generation jobs; polotno-node server-side renderer |
| Upload to S3 fails |
AWS credentials in .env; S3_* vars (two buckets in two regions) |
| Stock image search misses |
helper/stockImage.js; Pexels / Pixabay keys |
| Reference |
../../audit/someli-api/media-processing.md |
Dashboard / analytics issues
| Symptom |
Where to look |
| A chart shows wrong numbers |
dashboard/routes/index.js — find the endpoint feeding the chart |
| Leaderboard missing |
Leaderboard endpoint is in the someli-api/dashboard/ in-process copy but NOT in the standalone someli-dashboard-be (drift) |
| Local dev: dashboard empty |
In NODE_ENV=development the auth middleware on dashboard/routes/index.js is bypassed; check tDashboard* tables for data |
| Reference |
../../audit/someli-api/dashboard-analytics.md |
Realtime / Socket.IO issues
| Symptom |
Where to look |
| Client never receives a socket event |
App.socket from the shared App object; emit calls scattered through route handlers |
| Socket disconnects |
nginx → Socket.IO upgrade headers; check nginx.conf |
| Reference |
../../audit/someli-api/realtime-events.md |
Email / Slack notification issues
| Symptom |
Where to look |
| Email not sent |
@sendgrid/mail calls; SENDGRID_API_KEY, FROM env vars |
| Slack notification missing |
Slack token / channel constants; the integration is hardcoded in some places (known finding) |
| Reference |
../../audit/someli-api/notifications.md |
Deployment issues
| Symptom |
Where to look |
| Jenkins deploy failed |
Jenkinsfile in repo root; logs in Jenkins UI |
| GitHub Actions deploy failed |
.github/workflows/dev-api-deploy.yml; Actions tab on GitHub |
| PM2 says a job is "errored" |
Lightsail box; pm2 logs <job_name> |
| nginx error |
nginx.conf in repo + nginx logs on the Lightsail box |
| Body too large (HTTP 413) |
nginx caps at 100 MB; Express set to 150 MB; the nginx cap is the binding one |
| Reference |
../../audit/someli-api/deployment.md, ../../audit/someli-api/first-deployment.md |
Security / compliance issues
Cross-repo overlap (most common surprise)
If your task involves files like helper/aiLogics.js, helper/helper.js, helper/tokenGenerator.js, etc., always check whether the same file exists (and may have drifted) in:
Someli-admin-api/helper/designer-api/helper/
See ../../audit/CODE-OVERLAP-MATRIX.md for the file-by-file diff matrix.
When all else fails