Troubleshooting

Common issues and their solutions when running Mezite.

Agent Will Not Connect

If mezd fails to join the cluster:

Check the join token: Ensure the token has not expired.
Verify token bash
```
mezctl tokens ls
```
Generate a new one if needed: mezctl tokens create --roles=node --ttl=1h
Verify auth address: The agent must reach the auth service. Confirm MEZITE_AUTH_ADDR points to the correct host and port (default 3025).
Verify proxy address: The agent connects via a reverse tunnel on port 3024. Confirm MEZITE_PROXY_ADDR is set correctly.
Check firewall rules: Ports 3025 (auth) and 3024 (tunnel) must be reachable from the agent host.
Test connectivity bash
```
nc -zv mezite.example.com 3025
nc -zv mezite.example.com 3024
```

If msh ssh cannot connect to a node:

Check certificate expiry: Run msh status to see if your certificates have expired. Re-login with msh login if needed.
Check RBAC: Ensure your user has a role that grants access to the target node and login. Use mezctl roles get <role> to inspect role permissions.
Check node labels: If your role restricts access by label, verify the target node has the expected labels with mezctl nodes ls.

If msh login returns an error:

Password auth: Verify the username and password. Check if the user account is locked with mezctl users list.
OIDC / SSO: Ensure the auth connector is configured correctly.
Check connectors bash
```
mezctl connectors ls
```
Verify the OIDC issuer URL, client ID, and redirect URI match your identity provider configuration.
Proxy unreachable: Confirm you can reach the proxy on port 3080:
Test proxy connectivity bash
```
curl -k https://mezite.example.com:3080/healthz
```

If mezhub cannot connect to PostgreSQL:

Verify the MEZITE_DB_* environment variables (host, port, user, password, name, sslmode) are correct.

Ensure PostgreSQL is running and accepting connections:

Test database connection bash

psql "postgres://mezite:secret@localhost:5432/mezite?sslmode=disable" -c "SELECT 1;"

Check that the database and user exist, and that the user has the required privileges.
Review PostgreSQL logs for authentication or connection limit errors.

Increase log verbosity to diagnose issues. Set the MEZITE_LOG_LEVEL environment variable or pass the --log-level flag:

Set debug logging bash

# Via environment variable
export MEZITE_LOG_LEVEL=debug

# Via flag
mezhub --log-level=debug
mezd start --log-level=debug

Available levels: debug, info, warn, error.