Bridge Troubleshooting

If the connection between your FiveM server and Z-UCP isn't working, it's usually due to a misconfiguration. Here are the most common problems and their solutions.

Common Error Messages

1. 401 Unauthorized

Cause: The API key in your config.lua is invalid or belongs to another project. Solution:

• In the Z-UCP Admin Panel, go to "Project Settings" -> "API Key".
• Generate a new key and copy it exactly into config.lua.
• Make sure there are no spaces before or after the key.

2. Connection Refused / Timeout

Cause: Your server cannot reach our API (firewall) or the ApiUrl is incorrect. Solution:

• Check if Config.ApiUrl is set to https://api.z-hub.app.
• Make sure your server host allows outgoing connections on port 443 (HTTPS).
• Test the connection manually from your server terminal: curl https://api.z-hub.app/api/v2/health.

3. Bridge Secret Mismatch

Cause: The bridge secret in the panel doesn't match the one on the server. Solution:

• This secret is generated automatically. Restart the server to force a new handshake.

Troubleshooting Checklist

1. [ ] Is the plugin z-bridge entered in the server.cfg (ensure z-bridge)?
2. [ ] Does the server console show "Z-Bridge: Connected successfully" on startup?
3. [ ] Is your server's IP correctly entered in the Z-UCP settings (whitelist)?
4. [ ] Are you using the latest version of the bridge plugin?

Activate Debug Mode

If you can't find the problem, activate debug mode in config.lua:

Config.Debug = true

Restart the server and look at the z-bridge.log file in the plugin folder. All requests and error messages are logged there in detail.

Open Support Ticket