Troubleshooting & Logging
Relevant source files
The following files were used as context for generating this wiki page:
The Troubleshooting & Logging system in mt5-docker is designed to provide high availability and deep diagnostic visibility for the MetaTrader 5 (MT5) terminal and its gRPC/RPyC bridge running inside a Linux/Wine environment. It utilizes a multi-layered approach consisting of background health monitoring, fail-fast startup scripts, and detailed log parsing to ensure automated recovery and simplified human intervention.
Key components include the health_monitor.sh script, which tracks process and network health, and the open_demo_account.py wizard, which uses terminal log parsing to validate account provisioning. These systems cooperate with the s6-overlay supervisor to manage service lifecycles and restarts using token-based signaling.
Sources: README.md:28-30, docker/container/metatrader/health_monitor.sh:1-12
Logging Architecture
The project generates multiple log streams that capture different aspects of the system's state. These are primarily accessed via standard Docker logging mechanisms, though internal scripts also maintain specific log files and markers within the /config volume.
Standard Output (stdout) Logging
The core shell scripts (start.sh, setup.sh, health_monitor.sh) and the Python-based bridge and provisioning tools use a structured logging format to standard output. This allows administrators to use docker logs mt5 to monitor system activity in real-time.
Sources: docker/container/metatrader/setup.sh:22-27, docker/container/metatrader/health_monitor.sh:34-37
| Component | Log Source | Description |
|---|---|---|
| Startup | start.sh | Orchestration steps, environment exports, and setup success/failure. |
| Setup | setup.sh | Wine prefix initialization, MT5 installation progress, and package verification. |
| Health | health_monitor.sh | Failure counts, health check passes/fails, and restart requests. |
| Wizard | open_demo_account.py | GUI automation steps, log parsing results, and provisioning status. |
MT5 Terminal Logs
The MT5 terminal writes its own internal logs inside the Wine prefix. These are authoritative for connection status and account authorization. The provisioning system specifically parses these logs to confirm successful login, as the X11 window title may not always be available in headless modes.
Sources: docker/container/metatrader/open_demo_account.py:46-48, tests/test_static.py:456-465
The diagram shows the authoritative flow for validating account authorization through terminal log parsing.
Sources: docker/container/metatrader/open_demo_account.py:101-105, tests/test_static.py:488-500
Health Monitoring & Auto-Recovery
The health_monitor.sh script runs as a background daemon (when AUTO_RECOVERY_ENABLED=1) to ensure the MT5 terminal and the bridge server remain operational. It employs a failure threshold to prevent flapping during minor network or resource glips.
Health Check Sequence
The monitor performs three distinct checks in every interval (default 30 seconds):
- Process Check: Verifies
terminal64.exeis running viapgrep. - Listening Check: Verifies the bridge port (default 8001) is listening using
ss. - Response Check: Verifies the port responds to TCP connections using
nc.
Sources: docker/container/metatrader/health_monitor.sh:45-60
The sequence diagram illustrates the tiered health checking logic and the transition to a restart request.
Sources: docker/container/metatrader/health_monitor.sh:78-120
Recovery Configuration
Recovery behavior is controlled by several environment variables defined in the Docker Compose configuration and startup scripts.
| Variable | Default | Description |
|---|---|---|
HEALTH_CHECK_INTERVAL | 30 | Seconds between health check loops. |
FAILURE_THRESHOLD | 3 | Number of consecutive failures before triggering a restart. |
AUTO_RECOVERY_ENABLED | 1 | Enables/disables the background health monitor. |
RESTART_TOKEN | /tmp/.mt5-restart-requested | File used to signal the supervisor for a full service restart. |
| Sources: docker/container/metatrader/health_monitor.sh:17-25, docker/compose.yaml:57-58 |
Startup Troubleshooting
The setup.sh script utilizes a "Fail-Fast" design, where critical failures during the Wine prefix build or MT5 installation cause the container to exit immediately with a non-zero status. This prevents the system from entering a broken state where the bridge is running without a functional MT5 terminal.
Identifying Failures
Administrators should look for specific [ERROR] tags in the logs. Common failure points include:
- Wine Prefix Build: Fails if installers under
/opt/mt5-stagingare missing or if Xvfb cannot initialize. - Protobuf Mismatch: The bridge will fail to import if the Wine Python
protobufruntime version is older than the gencode version inmt5_pb2.py. - Installation Timeout: MT5 installation is capped at 300 seconds; exceeding this triggers a failure.
Sources: docker/container/metatrader/setup.sh:65-71, docker/container/metatrader/setup.sh:317-323, tests/test_static.py:410-425
Idempotency Markers
To assist in troubleshooting interrupted setups, the system uses "idempotency markers"—files that indicate a step was successfully completed.
.build-complete: Located in$WINEPREFIX, this confirms the Wine prefix (Mono, Gecko, Python) was built successfully. If missing,setup.shdeletes the directory and restarts the build..deps-installed: Indicateswinetricksor registry configurations were applied..mt5-startup-complete: Located in/tmp, signals the health monitor that it can begin its watch.
Sources: docker/container/metatrader/setup.sh:78-83, docker/container/metatrader/start.sh:45-51
Zero-Touch Provisioning Debugging
When MT5_AUTO_CREATE_DEMO=1 is enabled, the open_demo_account.py script automates the MT5 GUI. This process is susceptible to timing issues or GUI changes in newer MT5 builds.
Common Issues & Mitigation
- Focus Stealing: MT5 may open "LiveUpdate" or web-view popups on first run. The script attempts to dismiss these using
wmctrlandxdotoolescape sequences. - Log Decoding: MT5 logs are encoded in UTF-16LE. Attempting to read them as UTF-8 will result in
Nonevalues for account logins. The system uses explicit UTF-16 decoding to prevent this. - Restart Persistence: If
MT5_DEMO_PERSIST_CREDS=1is set, the wizard captures the password from the "Registration Information" clipboard. Failure to capture this password is treated as a fatal error if persistence is required.
Sources: docker/container/metatrader/open_demo_account.py:214-225, docker/container/metatrader/open_demo_account.py:255-265, tests/test_static.py:456-465
# Example of log parsing for authorized login validation
# Sources: [docker/container/metatrader/open_demo_account.py:293-305](https://github.com/marlonsc/mt5-docker/blob/5b724cc1782a07848e8667a662bca5081606a822/docker/container/metatrader/open_demo_account.py#L293-L305)
def authorized_login_from_terminal_log(cursor: LogCursor | None = None) -> str | None:
login: str | None = None
for line in terminal_log_lines(cursor):
line_lower = line.lower()
if "authorization" in line_lower and "failed" in line_lower:
login = None
continue
match = LOG_AUTHORIZED_RE.search(line)
if match:
login = match.group(1)
return login
Troubleshooting Summary
In summary, troubleshooting the mt5-docker container primarily involves inspecting the Docker logs for [ERROR] or [WARN] tags generated by the internal orchestration scripts. Automated recovery is handled by the health_monitor.sh script, which tracks the MT5 process and bridge port health, requesting restarts via a token-based system if failures exceed the defined threshold. For provisioning issues, checking the /config/auto_demo.json file and verifying that MT5 terminal logs are being correctly decoded as UTF-16 are the most critical diagnostic steps.
Sources: README.md:275-285, docker/container/metatrader/health_monitor.sh:8-12