Troubleshooting guide for common RedM server issues including license key errors, server browser visibility, resource failures, client connections, database problems, and performance optimization. For initial setup instructions, see our RedM Server Setup Guide.
License Key Errors
License key issues are the most common problem when starting a new RedM server. Here are the typical errors and their solutions:
"Invalid license key" or "Could not authenticate"
| Cause | Solution |
|---|---|
| License key is mistyped or has extra spaces | Copy the key directly from Keymaster. Remove any leading/trailing whitespace from the CFX_LICENSE startup variable in GPanel or the sv_licenseKey line in server.cfg. |
| IP address mismatch | The key is registered to a different IP than your server's actual IP. Go to Keymaster, check the registered IP, and update it to match your server's IP shown in GPanel. |
| Key set in both GPanel and server.cfg with different values | Ensure the key is consistent. It is best to set it in the GPanel startup variable and let the egg handle passing it to the server. Remove or comment out sv_licenseKey from server.cfg if GPanel handles it. |
| Cfx.re account issue or key revoked | Log in to Keymaster and verify the key is still active. Generate a new key if the old one was deleted or expired. |
| Keymaster service is temporarily down | Check Cfx.re status page for outages. Wait and try again later. |
Important: If you recently received a new server or your server IP changed (e.g., after a node migration), you must update the IP in Keymaster or generate a new license key. The old key will not work on a different IP.
Server Not Appearing in Browser
If your server is running but players cannot find it in the RedM server browser:
Checklist
- Wait at least 5 minutes. After starting, the server needs time to register with the Cfx.re master server list. New servers may take several minutes to appear.
- Verify the license key is valid. The server will not be listed without a working license key. Check the server console for license-related errors.
- Check endpoint configuration. Ensure
endpoint_add_tcpandendpoint_add_udpinserver.cfguse the correct port:
The port must match the one assigned in GPanel.endpoint_add_tcp "0.0.0.0:30120" endpoint_add_udp "0.0.0.0:30120" - Check for "sv_master1" or listing settings. Ensure you have not accidentally set the server to not list itself. There should be no
sv_master1 ""in your config (this disables master list registration). - Verify the server is actually running. Check the GPanel console. If the server crashed or stopped, it will not appear in the browser.
- Try direct connect. Even if the server is not in the browser, direct connect should work. Have a player press F8 in RedM and type:
connect YOUR_SERVER_IP:PORT
Tip: You can verify your server is reachable by using the Cfx.re server lookup. Try navigating to
http://YOUR_SERVER_IP:PORT/info.json in a web browser. If the server is running and accessible, it will return a JSON response with server information.
Resource Loading Failures
Resource errors are common when adding new scripts or frameworks to your server. Here are the most frequent issues:
"Could not find resource [resource_name]"
- The resource folder does not exist in the
resources/directory, or is in the wrong location. - The folder name does not match the name used in
ensure. Resource names are case-sensitive. - Fix: Verify the resource folder exists and the name in
server.cfgmatches exactly. Use GPanel file manager or SFTP to check.
"Failed to load resource [resource_name]: manifest error"
- The resource's
fxmanifest.luaor__resource.luahas a syntax error. - The manifest references files that do not exist in the resource folder.
- Fix: Open the manifest file and check for typos, missing commas, or references to non-existent files. Check the server console for the specific line number of the error.
"Error loading script [filename]: [error details]"
- A Lua, C#, or JavaScript file within the resource has a syntax or runtime error.
- Fix: Read the full error message in the console. It will include the file name and line number. Common causes include:
- Missing dependencies (another resource that must be loaded first)
- Outdated resource not compatible with current RedM server version
- Incorrect configuration values in the resource's config file
Resource Load Order Issues
Resources in server.cfg are loaded in the order they appear. If a resource depends on another (e.g., vorp_inventory depends on vorp_core), the dependency must be listed first:
# Correct order - dependencies first
ensure oxmysql
ensure vorp_core
ensure vorp_inventory
ensure vorp_stores
# Wrong order - will cause errors
# ensure vorp_inventory <-- depends on vorp_core
# ensure vorp_core <-- loaded too late
Warning: If a resource fails to load, any resources that depend on it will also fail. Always check the console output carefully to identify the root cause, which is usually the first error that appears.
Client Connection Issues
When players cannot connect to your server:
"Connection timed out" / "Failed to connect"
| Cause | Solution |
|---|---|
| Server is not running | Check GPanel console to confirm the server is online and not crashed. |
| Wrong IP or port | Verify the player is using the correct IP and port from GPanel. See How to Find Your Server IP and Port. |
| Endpoint misconfiguration | Ensure endpoint_add_tcp and endpoint_add_udp in server.cfg use port 0.0.0.0:PORT where PORT matches GPanel. |
| Server is full | Check if sv_maxclients has been reached. Increase the value if your hosting plan allows it. |
"Connection rejected by server"
- Server password: If
sv_passwordis set, the player must enter the correct password. - Whitelist/allowlist resource: If you have a whitelist resource enabled, the player must be approved before connecting.
- Ban: The player may be banned. Check your ban list or database for their identifiers.
Client crashes on connect
- A resource on the server is sending bad data or has a client-side script error that crashes the client.
- Fix: Disable recently added resources one at a time to identify the problematic one. Check the server console for errors during client connection.
- Ensure the player's RedM client is up to date.
"Could not download file" errors
- The server is trying to send a large file (e.g., a streaming asset) that exceeds transfer limits or the connection is unstable.
- Fix: Reduce the size of streamed assets, use a CDN/external hosting for large files if supported, or have the player retry the connection.
Database Problems (MySQL / oxmysql)
Most RedM roleplay frameworks use MySQL for persistent data storage. The most common database connector is oxmysql.
Connection Failed Errors
If oxmysql (or another MySQL connector) fails to connect, check the following:
# Typical oxmysql connection string in server.cfg
set mysql_connection_string "mysql://user:password@host:3306/database_name?charset=utf8mb4"| Error | Solution |
|---|---|
ECONNREFUSED or "Connection refused" |
The MySQL server is not running, the host/port is wrong, or the MySQL server is not accepting external connections. Verify the host, port, and that your database server is online. |
ER_ACCESS_DENIED_ERROR |
Wrong username or password in the connection string. Double-check credentials in your database hosting panel. |
ER_BAD_DB_ERROR |
The database name does not exist. Create the database first through your database management panel (phpMyAdmin, etc.). |
ETIMEDOUT |
The database server is unreachable. Check if there are firewall rules blocking the connection, or if the database host is correct. |
| "Too many connections" | The database has hit its maximum connection limit. This can happen if resources are not properly closing connections, or if the limit is too low. Restart the server and check your MySQL max_connections setting. |
Tip: If your RedM server and MySQL database are on the same machine, use
localhost or 127.0.0.1 as the host. If they are on different servers, use the database server's IP address and ensure the MySQL user has remote connection privileges.
Missing Tables or Schema Errors
Roleplay frameworks often require database tables to be set up before they can function:
- Check the framework's documentation or GitHub repository for SQL import files (often named
database.sql,schema.sql, or similar). - Import the SQL file into your database using phpMyAdmin or a MySQL client.
- Some frameworks auto-create tables on first start. Ensure the database user has
CREATE TABLEprivileges.
Performance Issues
If your RedM server is experiencing lag, low tick rate, or general poor performance:
Identifying Performance Problems
Check the server console for performance warnings. RedM servers target a tick rate of around 30-64 ticks per second. You can monitor this with:
- txAdmin dashboard: If txAdmin is available, it shows real-time server performance metrics.
- Server console: Watch for "slow tick" or "resource hitch" warnings.
- resmon command: Type
resmon 1in the server console (or F8 console) to enable the resource monitor, which shows CPU time per resource.
Common Performance Solutions
| Issue | Solution |
|---|---|
| High CPU usage from a specific resource | Use resmon 1 to identify the resource. Consider replacing it with a more optimized alternative, or contact the resource developer. |
| Too many resources loaded | Each resource consumes server resources. Audit your resource list and remove any that are unused or redundant. |
| Database query bottleneck | Slow or unindexed database queries can cause server hitches. Check oxmysql slow query warnings in the console. Add indexes to frequently queried columns. |
| High player count causing lag | Reduce sv_maxclients to a level your server hardware can handle. Consider upgrading your hosting plan for more resources. |
| OneSync entity limits | Too many spawned entities (peds, vehicles, objects) can degrade performance. Use resources that clean up unused entities. |
| Memory leaks | Some poorly coded resources leak memory over time. Monitor server RAM usage in GPanel. Regular server restarts (every 6-12 hours) can mitigate this. |
Recommended Practices
- Schedule automatic restarts every 6-12 hours using GPanel's schedule feature or txAdmin to clear accumulated memory and entity issues.
- Keep resources updated to benefit from performance fixes and optimizations.
- Avoid duplicate functionality — do not run two resources that do the same thing (e.g., two weather systems).
- Test new resources on a staging server (or with low player count) before deploying to your main server.
- Monitor server metrics regularly through GPanel or txAdmin to catch problems early.
Note: If you are consistently experiencing performance issues despite optimization, your server may need a higher-tier hosting plan with more CPU and RAM resources. Contact our support team to discuss upgrade options.
General Troubleshooting Tips
- Always read the server console output. Almost every error includes a message in the console that tells you what went wrong and where.
- Restart the server after config changes. Most changes to
server.cfgrequire a full server restart to take effect. - Disable resources one at a time to isolate problems. Comment out
ensurelines inserver.cfgwith#. - Keep backups of working configurations before making changes. Download your
server.cfgand database before major updates. - Check Cfx.re forums and documentation at docs.fivem.net for official documentation that applies to both FiveM and RedM.
- Verify resource compatibility with your server version. Resources built for older versions may not work with current RedM builds.
Related Articles
- RedM Server Setup Guide — License keys, server.cfg configuration, resource management, and connecting.
- How to Find Your Server IP and Port
- How to Upload Files via SFTP
- Getting Started with Your New Server
Need Help?
Still experiencing issues with your RedM server? Open a support ticket and include any error messages from your server console. Our team will help you diagnose and resolve the problem.
