Troubleshooting

Troubleshooting & FAQ

Startup errors

The app validates everything on boot and exits (sys.exit(1)) on failure. Read the CRITICAL ERROR line printed to stderr.

Message	Cause	Fix
Failed to load config from <url>	The remote config.json couldn't be fetched or parsed.	Check internet access / CONFIG_URL. See Configuration.
Missing config.json key(s): ...	RELEASEVERSION or MAJOR_LOGIN_URL absent in the config JSON.	Add the missing key(s) to your config source.
Missing environment variable(s): ...	VALID_API_KEY, ADMIN_KEY or DATABASE_URL not set.	Set them in .env / the environment.
Failed to connect to Neon PostgreSQL database	Bad DATABASE_URL or unreachable DB.	Verify the connection string, SSL mode, and that the DB is awake.

Request errors

Status	Body	Meaning
400	Missing uid or password.	Add uid and password query params.
401	Invalid API key. ...	Key isn't the master key and isn't in the DB.
401	API key has expired or is invalid.	Key is revoked or past expires_at.
401	Unauthorized admin access.	Wrong/missing X-Admin-Key on an admin route.
500	Database verification failed.	DB lookup error during key check.
500	Token generation failed.	Upstream login handshake failed (see below).

"Token generation failed" — what to check

This wraps any exception from the Garena/Free Fire handshake. Common causes:

1. Wrong RELEASEVERSION. After a game update, the old version is rejected. Update RELEASEVERSION in your config.json.
2. Stale MAJOR_LOGIN_URL. The login host changed. Update it in config.json.
3. Invalid guest credentials. The uid/password are wrong or the account is banned.
4. Upstream rate‑limiting / network issues. Retry; check outbound connectivity.

Enable Flask debug logs (already INFO level) to see the full stack trace — the app logs JWT generation failed with the exception.

FAQ

Q: Do I need a database just to test? Yes — DATABASE_URL is required at startup even if you only use the master key. Any PostgreSQL works; Neon is the default target.

Q: How do I issue keys to other users? Use the admin API to mint 1/3/7/30‑day keys. See Admin API.

Q: Can I revoke the master key? Not via the API — it lives in the VALID_API_KEY env var. Rotate the variable and redeploy.

Q: Where do RELEASEVERSION and the login URL come from? A remote config.json fetched at startup, so they can be updated without redeploying. See Configuration.

Q: Is this safe to expose publicly? The auth endpoint accepts game credentials, so put it behind HTTPS and only hand out keys to trusted users. Never expose your ADMIN_KEY.

Still stuck?

Open an issue on the GitHub repository.