Troubleshooting

Common issues and how to fix them. Enable debug: true in config.yml for detailed logs.

Symptoms: No "Client authenticated" message on Velocity. Backend logs show connection errors or timeouts.

Checklist:

Secret mismatch → the secret in each backend's config must match Velocity's secret.key file contents
Wrong host → if both run on the same machine, use 127.0.0.1. If on different machines, the backend's host must point to Velocity's external IP or domain
Port closed → make sure bind-port on Velocity is open in your firewall and matches the backend's port
TLS mode mismatch → both sides must use the same tls-mode (PLAIN, TOFU, or STRICT)
Start order → start Velocity first, then backends. The proxy must be listening before clients connect.

Another process is using the configured port.

Fix: Change bind-port to an unused port (e.g. 8766) on Velocity and all backends, then restart.

Symptoms: /cb list shows the client as connected, but running a script command does nothing.

Checklist:

Script not loaded → check /cb scripts to verify the script appears. If not, check for YAML syntax errors in the server log.
Scripts are Velocity-only → all scripts must be in plugins/commandbridge/scripts/ on the Velocity proxy, even if they register commands on backends.
Missing permissions → the player needs commandbridge.command.<name> unless permissions.enabled is false in the script
Target client ID mismatch → the id in execute must match the backend's client-id exactly
Client disconnected → if the target backend disconnected after /cb list was run, the command will fail silently

The player lacks the required permission node.

Fix:

Grant commandbridge.command.<name> on the correct side (where the command is registered), or
Set permissions.enabled: false in the script to disable checks, or
Set permissions.silent: true to suppress the message (the command still won't run)

Error	Cause	Fix
`SSL handshake failed`	TLS mode mismatch	Set the same `tls-mode` on both sides
`Certificate pin mismatch`	Proxy cert was regenerated	Clear `tls-pin` on the backend, restart
`PKIX path building failed`	STRICT mode with bad keystore	Check `keystore-path`, `keystore-password`, and `keystore-type`

See the Security page for detailed TLS setup.

${arg} placeholders require matching argument names in the args list
PlaceholderAPI (%placeholder%) requires PAPI on the backend and PapiProxyBridge on Velocity
PAPI placeholders only resolve when the executor is a player (not console)
Check spelling and case. Placeholder names are case-sensitive.

CommandBridge validates scripts at load time. Common errors:

name does not match pattern → script name must be lowercase, 3-33 chars, start with a letter, only a-z0-9-.
required field missing → add the missing field. All of version, name, permissions, register, defaults, args, commands are required.
platform mismatch → you used a backend-only argument type (like PLAYERS) in a command registered on Velocity. Either register on a backend or use a universal type.
unknown argument type → check spelling against the Argument Types list.

Enable debug logging for detailed output:

debug: true

Or toggle it at runtime:

/cb debug

Debug logs include WebSocket frames, auth handshakes, command dispatch steps, and placeholder resolution.

If you're still stuck:

Content: