Troubleshooting

Troubleshooting & FAQ

Common problems, what they mean, and how to fix them. Turn on debug logging first — it usually tells you exactly what's wrong:

mysql_debug(true);   // prints [omp-MySQL] diagnostics to the console

(In the mysql-admin demo: /mysql debug on via RCON.)

---

Connection problems

"DB connect FAILED" / mysql_connect returns MYSQL_INVALID_HANDLE

Check mysql_errno / mysql_error and the [omp-MySQL] debug line. Most common causes:

Symptom in the log	Cause	Fix
Can't connect / Connection refused	MySQL isn't running, or wrong host/port	Start MySQL; verify host/port (default 3306). Test: mysql -u user -p -h 127.0.0.1
Access denied for user	Wrong username/password, or the user isn't allowed from your host	Re-check credentials; the user's host ('user'@'host') must match where you connect from
Unknown database	The database doesn't exist	CREATE DATABASE mydb; or fix the name
Unknown server host	Bad hostname / DNS	Use an IP like 127.0.0.1; check spelling
TLS/SSL error	See the TLS section below	—

"connection is not encrypted; refusing it"

The server doesn't support TLS, so omp-MySQL refused (it's fail-closed). You're almost certainly on MySQL 5.6 or older (no default TLS), or TLS is disabled on the server. Use MySQL 5.7+ (8.4 LTS recommended). See MySQL versions.

"self-signed certificate in certificate chain"

You used SSL_MODE_VERIFY_CA/VERIFY_IDENTITY but didn't give a CA the server's cert chains to. Either:

• supply the CA: mysql_config_set(cfg, SSL_CA, "scriptfiles/ca.pem"), or
• for local/dev, use SSL_MODE_REQUIRED (encrypt without verifying the cert).

How to get the CA is in Configuration.

"Hostname verification failed"

VERIFY_IDENTITY checks that the certificate's name matches the host you connect to. MySQL's auto-generated cert uses a generic name. Fix by connecting to a name in the cert, regenerating the server cert with your host/IP in its SAN, or dropping to VERIFY_CA. See Security.

---

Query & callback problems

callback "OnSomething" not found

The callback function doesn't exist where the component looked. Check:

• It's spelled exactly the same in mysql_execute(..., "OnSomething") and public OnSomething().
• It's forward-ed and public.
• It exists in a loaded script (gamemode or a loaded filterscript).

My callback never fires

• Did the query fail? Add an OnQueryError handler, or check mysql_debug(true) output.
• Are you reading the result inside the callback? The result set is only active there.

mysql_rs_get_* returns 0 / empty

• The query returned no rows — check mysql_rs_row_count(rows) first.
• Wrong column name — it must match the SELECT exactly (use an alias: SELECT COUNT(*) AS c).
• You're reading after the callback ended — read while it's still running.

Prepared statement does nothing / wrong values

• Parameter indices are 1-based: the first ? is index 1, not 0.
• Bind a value for every ? before mysql_stmt_execute.
• See Prepared statements.

---

Component / loading problems

The component doesn't load (Windows)

• Make sure libssl-3.dll and libcrypto-3.dll are next to omp-server.exe (they ship in the Windows release zip). The DLL needs them at runtime.
• You need the Microsoft Visual C++ runtime (most systems have it).

The component doesn't load (Linux)

• omp-mysql.so goes in components/. It's built for glibc 2.31 (matches the open.mp Linux server) — use the released binary rather than building on a very new distro.

Nothing happens at all

• Confirm the component loaded: the console prints omp-mySQL v1.0.0 loaded on start.
• Confirm #include <omp-mysql> compiles (the .inc is in qawno/include/).

---

Security questions

"What if a player puts SQL in the login box?"

Nothing — passwords are only hashed and compared, never put into SQL. Player input in queries is handled with prepared statements or %e escaping. See Security.

"What if someone rejoins / takes another player's slot — are they auto-logged-in?"

No. Session state is wiped on every connect; login always requires the password. (The mysql-admin demo enforces this.)

"Who becomes admin first?"

Nobody automatically. In the mysql-admin demo, everyone registers as a Player; the first admin is promoted via RCON (/setlevel). See mysql-admin demo.

---

Still stuck?

• Turn on mysql_debug(true) and read the [omp-MySQL] lines.
• Check mysql_errno/mysql_error after a failed call.
• Open an issue: https://github.com/Mac-Andreas/omp-MySQL/issues — include the debug log, your MySQL version, and the smallest code that reproduces it.