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

SSH Connection Fails

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.

Login Fails

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 list
    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

Database Connection Issues

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.

Log Levels

Increase server log verbosity to diagnose issues. mezhub reads its log level from the log.level field in mezite.yaml or from the MEZITE_LOG_LEVEL environment variable. There is no --log-level CLI flag.

Set debug logging on mezhub bash 
# Env var or mezite.yaml — equivalent.
export MEZITE_LOG_LEVEL=debug
mezhub --config=mezite.yaml

Available levels: debug, info, warn, error.

The mezd agent currently runs at zap's production-default level and does not honour a log-level flag or env var. If you need verbose agent logs while debugging, restart mezd under strace/journalctl with full systemd output rather than trying to dial in the log level.