Hermes Gateway Troubleshooting Guide — Known Errors & Fixes
This page documents known errors, their causes, and how to resolve them.
Error Reference
Could not connect (invalid user 'username' - multiple entries: 2)
Cause: Hermes Gateway is configured with passthru authentication (the default), but the upstream database does not allow plaintext passwords.
Fix: Configure the upstream MySQL/MariaDB instance to allow plaintext passwords, or switch to a different authentication method. See the Security Guide and the MySQL documentation for details.
panic: dial tcp xxx.xx.x.x:3399: i/o timeout
2025-01-26 20:42:37 Error connecting mysql: dial tcp 172.22.0.1:3399: i/o timeout
2025-01-26 20:42:26 panic: dial tcp 172.22.0.1:3399: i/o timeout
Cause: The upstream server is reachable at the network level, but Hermes Gateway cannot establish a TCP connection — typically a firewall rule or a port mismatch in configuration.
Fix: Verify that the upstream host and port in your configuration match the actual database listener, and that no firewall is blocking the connection.
panic: dial tcp 172.22.0.1:3306: connect: connection refused
2025-01-26 20:41:23 Error connecting mysql: dial tcp 172.22.0.1:3306: connect: connection refused
2025-01-26 20:41:23 panic: dial tcp 172.22.0.1:3306: connect: connection refused
Cause: The upstream database is not listening on the configured port. The database may be down, not yet started, or listening on a different port.
Fix: Confirm the upstream database is running and accepting connections on the expected port before starting Hermes Gateway.
Server Not Starting (exit status 2, silent failure)
2025-02-23 04:15:02 INFO spawned: 'dbgw' with pid 76
2025-02-23 04:15:02 Reading config file...
2025-02-23 04:15:02 &{host.docker.internal 3306 demodata root 123456 ...}
2025-02-23 04:15:02 Redis cache
2025-02-23 04:15:02 Redis PubSub
2025-02-23 04:15:02 INFO exited: dbgw (exit status 2; not expected)
2025-02-23 04:15:03 INFO gave up: dbgw entered FATAL state, too many start retries too quickly
Cause: Known issue in version 0.1.2 — Hermes Gateway exits silently with rc=2 when started with a config.json file. The root cause is under investigation.
Fix: Upgrade to a later version. If you must use v0.1.2, try switching to environment variable-based configuration instead of a JSON config file.