Troubleshooting & FAQ
Relevant source files
The following files were used as context for generating this wiki page:
This guide provides technical information for diagnosing issues and answering common questions regarding Matterbridge, a multi-protocol chat bridge. It covers common configuration hurdles, build requirements, and operational flags used to monitor the bridge's health and connectivity.
Execution and Debugging
When encountering issues with message delivery or connectivity, the primary diagnostic tool is the -debug flag. This provides verbose logging output that can be used to trace the flow of messages between protocols.
CLI Flags
The following flags are available for the matterbridge binary:
| Flag | Type | Description |
|---|---|---|
-conf | string | Path to the configuration file (default: "matterbridge.toml"). |
-debug | boolean | Enables debug logging for detailed internal activity. |
-gops | boolean | Enables the gops agent for profiling and diagnostics. |
-version | boolean | Displays the current version of the binary. |
Sources: README.md:214-222
Monitoring and Health
Matterbridge provides a basic API for checking system status. Developers can use the /health endpoint to verify if the server process is alive.
The diagram above shows the simple request-response flow for health checks.
Sources: contrib/api.yaml:15-23
Build and Compilation Issues
Compilation of Matterbridge can be resource-intensive or restricted by specific library requirements (such as WhatsApp support).
Memory Requirements
Building the binary with all bridges enabled requires approximately 3GB RAM. If the build environment is resource-constrained, users can reduce this to 0.5GB RAM by using build tags to exclude specific bridges, such as Microsoft Teams or Zulip.
Sources: README.md:143-159
CGO and Binary Portability
Matterbridge can be built without a C compiler by setting CGO_ENABLED=0. This is particularly useful for cross-compilation or when building for environments where gcc is unavailable.
Sources: README.md:147-148
Dependency and System Issues
Since Matterbridge relies on sys/unix for low-level system calls on non-Windows platforms, issues may arise if the underlying OS headers are inconsistent with the generated Go files in the vendor directory.
Sources: vendor/golang.org/x/sys/unix/README.md:13-25
Configuration Diagnostics
Most operational failures are rooted in the matterbridge.toml configuration. Matterbridge uses the go-toml library for parsing.
Common Configuration Errors
- Protocol Mismatch: Accounts must be defined in the format
[protocol.accountname]. - Gateway Mapping: Gateways must explicitly list the accounts and channels they are bridging.
- TOML Syntax: Since
go-tomlprovides line and column position data for errors, users should look at the terminal output for specific syntax errors during startup.
Sources: README.md:173-207, vendor/github.com/pelletier/go-toml/README.md:40-45
Protocol-Specific Troubleshooting: IRC
IRC connectivity often fails due to nick collisions or validation errors. The underlying girc library handles:
- Nick collision detection and prevention.
- Event/message rate limiting.
- Channel and user validation.
Sources: vendor/github.com/lrstanley/girc/README.md:65-71
API and Message Flow
When using the Matterbridge API to build 3rd party integrations, understanding the message structure is critical for troubleshooting "missing" message fields.
Message Structure
The API differentiates between IncomingMessage (from the bridge to the API) and OutgoingMessage (from the API to the bridge).
This diagram illustrates the flow of a message originating from an external application through the API.
Sources: contrib/api.yaml:24-43
API Data Model (Key Fields)
| Field | Source | Description |
|---|---|---|
gateway | Both | Required. Maps to the gateway name in .toml. |
event | Incoming | Specific event type (e.g., join, part, message). |
extra | Incoming | Contains data like base64 encoded files or protocol-specific metadata. |
id | Incoming | Unique ID of the message on the sending bridge. |
Sources: contrib/api.yaml:61-125
FAQ
Q: Why can't I find binaries for WhatsApp multidevice support?
A: The library used for WhatsApp multidevice support includes a GPL3 library. Providing pre-compiled binaries would require Matterbridge to change its overall license to GPL, so users must build it themselves using -tags whatsappmulti.
Sources: README.md:161-166
Q: Does Matterbridge require Mattermost to run?
A: No, Mattermost is not a requirement. Despite the name, Matterbridge is a standalone bridge that supports dozens of protocols natively.
Sources: README.md:39
Q: How do I handle message edits and deletes?
A: Matterbridge supports these natively across protocols that provide the functionality, though specific support varies by protocol capabilities.
Sources: README.md:73
Q: How do I start the bridge with a specific configuration?
A: Run the binary with the -conf flag: ./matterbridge -conf myconfig.toml.
Sources: README.md:215
Matterbridge's troubleshooting primarily involves verifying configuration syntax via TOML standards, monitoring API health, and using the -debug flag to isolate protocol-specific communication failures. Proper build tags are essential for managing memory usage and licensing requirements for specific protocols like WhatsApp or Microsoft Teams.