Appearance
Troubleshooting
Start with the failing component’s own log and the earliest useful error. Avoid launching duplicate processes or importing the clean schema as a general repair command.
Game will not start
| Symptom | Check |
|---|---|
| Cannot load gamemode | Correct non-empty gamemodes/gamemode.amx, script name and working directory |
| Missing native/plugin error | Platform/build compatibility, component versus plugin placement, library dependencies |
| MySQL failure | mysql.ini, credentials, database name, host/network and database logs |
| ColAndreas fatal error | Exact collision-file path/case, valid generated file and compatible plugin |
| Address already in use | Existing game process and chosen UDP/artwork TCP ports |
| Starts then stops | Read log.txt through the full startup sequence, not just the agent’s start response |
On Linux, use ldd on the runtime/plugins to find missing dependencies. The engine is a 32-bit application; the host may need the corresponding runtime libraries.
Web build or startup fails
- Run commands in
web-platform/web/, not the framework root. - Use the supported Node version and
npm ciwith the checked-in lockfile. - Generate Prisma after installation/schema changes.
- Confirm the web Docker context is
web-platform/, Dockerfileweb/Dockerfile. - For the separate framework project website repository, use its root
Dockerfileand target HTTP port 80. - Run the supplied standalone
npm startafternpm run build; do not replace it withnext start. - On Windows, stop the running standalone app before rebuilding if output directories report
EBUSY.
Login, cookies and email
| Symptom | Check |
|---|---|
| Login loops on public host | HTTPS origin, AUTH_URL, proxy host/protocol and secure cookies |
| Account rejected despite correct password | Active ban, reset-required state, rate limit or pending 2FA code |
| Reset-required account | Complete the password-recovery flow using the registered email |
| Code expired/invalid | Latest message, five-minute expiry, attempts, single-use and resend cooldown |
| No emails | SMTP connectivity/authentication, allowed sender, TLS settings, provider restrictions and web logs |
| Email link points to localhost | Correct AUTH_URL and restart web |
| Missing table/column | Review/apply additive SQL migration; do not reset the live database |
See the mail guide for DNS, certificates and delivery diagnosis. A successful SMTP connection is not proof of inbox delivery.
ACP cannot control the game
Check the agent process and private URL/key first. A 401/403 can be an authentication/role issue; a 502 can mean the agent is unreachable. Verify the operation’s actual rank requirement.
If the game is running independently, agent status can still say stopped. Stop the independent process and start through the agent. In containers, verify shared process ownership rather than only a shared mount.
Missing uniforms or equipment
Check faction membership, locker enabled state, range, interior/world and squad. Check equipment type/row, tier and duty conditions. Use /reloadarmories after equipment edits and /reloadfskins after uniform-row edits. Custom asset registration changes require a full game restart.
For stock uniform creation, use the faction owner’s /fskinadd flow. ACP can edit usable-row metadata even when custom uploads are disabled. Do not expect the disabled custom-upload section to create stock rows.
Jobs do not offer a route
Place the depot and create eligible business records first. Trucker destinations require supported buy types, normal exterior interior/world and the minimum distance. Use a supported registered cargo vehicle, not an arbitrary temporary engine vehicle.
Data changes disappear
The game keeps in-memory entity/character arrays. Editing SQL or web data while the relevant state is loaded can be overwritten by a later save. Use supported commands, documented reloads and offline-edit requirements. Keep a backup before diagnosing persistent-data issues.