Cursor Troubleshooting

Setup & Build

Problem	Solution
backend/ or frontend/ missing	In Cursor, run build then ./run.sh.
Agent pauses on every cd, npm, or docker-compose command	Cursor Settings → Agent → Terminal → Allowlist (with Sandbox), and allowlist cd, mkdir, npm, ./run.sh, docker, docker-compose, node, lsof.
Build wizard doesn't appear, or agent scaffolds without asking config questions	Switch to Plan mode (Shift+Tab), then type build again and confirm when prompted.

Problem	Fix
Health is OK but hotel search/booking returns 502 or auth errors	TRAVCLAN_API_KEY, TRAVCLAN_USER_ID, or TRAVCLAN_MERCHANT_ID in backend/.env are missing or invalid. Run configure env in Cursor and paste real sandbox keys, then ./run.sh stop && ./run.sh.
Browser CORS error	APP_ALLOWED_ORIGINS in backend/.env must include http://localhost:5173. Update and restart with ./run.sh stop && ./run.sh.
Backend container exits or health check times out	Run ./run.sh status and cd backend && docker compose logs --tail=50 api. Usually a port conflict, Docker not running, or stale containers.
Container name already in use	./run.sh stop, then cd backend && docker compose down --remove-orphans, then ./run.sh.
Filebeat container restarting in a loop	Logging is enabled without Elasticsearch configured. Either set LOGGING_ENABLED=false, or run add elastic server to set it up properly.

Problem	Fix
Connection refused / network error from the browser	frontend/.env must have VITE_API_BASE_URL=http://localhost:8000 (no trailing slash), and the backend must be running.
Hotel search completes but no hotels appear	Volt returns hotels in results.data, not results.hotels — fix the parsing path.
Rooms, price-check, or booking fail after the app was idle ~60 min	The traceId from hotel search expired. Start a new search from the home page.
Booking fails with valid keys	Use ISD code 91 not +91. Also check that status === "Failed" responses show an error instead of navigating to confirmation.
Search/Continue/Confirm buttons look blank	White-on-white CSS — primary CTAs must use the brand color with white text.