Troubleshooting

You see	Cause and fix
The web app shows an offline state for data	The API on port 5000 isn't running. docker compose ps, then docker compose logs api.
/api/v1/health answers 503	MySQL or Redis is down. docker compose up -d and check the logs.
Settlement or data-quality pages are empty	Tables or seed rows are missing: docker compose exec api alembic upgrade head, then docker compose exec api flask --app wsgi seed.
next dev serves code you already changed	Stop it, delete frontend/.next, start again.
CI fails on openapi.json or the generated types	Run python write_openapi.py in backend and npm run api:types in frontend, then commit both.
Tests can't connect to the database	Start the Compose MySQL and set TEST_DATABASE_URL in .env.
404 unknown_market for NYSE	Use the MIC: XNYS. Codes are case-sensitive.
400 year_out_of_range	The library has no data for that market and year.
400 no_default_cycle	No settlement cycle is on file for one of the markets on that date; pass cycle.
Every visitor shares one rate limit in production	The reverse proxy isn't setting X-Forwarded-For.

Still stuck? Open an issue.