Mattermost Fails to Start After apt Upgrade: Port 443 Permission Denied

Applies to: Mattermost — Self-hosted on Ubuntu (and other Debian-based distributions) with Mattermost configured to listen directly on port 443
Symptoms: Mattermost service fails to start after an apt upgrade; dpkg post-installation script returns exit status 1; service logs show Error starting server, err:listen tcp :443: bind: permission denied.

🛑 Problem

On Linux, ports below 1024 are considered privileged and require special permissions to bind to. When Mattermost is configured to listen directly on port 443, the Mattermost binary is typically granted the CAP_NET_BIND_SERVICE capability so the unprivileged mattermost user can bind to that port.

When Mattermost is upgraded via apt, the package replaces the binary at /opt/mattermost/bin/mattermost. Any Linux capabilities previously set on the old binary are not preserved on the replacement, so the service fails to start until the capability is re-applied.

The failure typically surfaces in the following ways:

• The apt upgrade output reports a post-installation script failure with exit status 1
• systemctl status mattermost.service shows the service as failed with code=exited, status=1/FAILURE
• The service logs (journalctl -u mattermost.service --no-pager -n 200 or /opt/mattermost/logs/mattermost.log) contain the error: Error starting server, err:listen tcp :443: bind: permission denied

💡 Tip: If your environment uses a reverse proxy such as nginx or Apache to handle TLS on port 443 and forwards traffic to Mattermost on a higher port like 8065, this article does not apply. Mattermost itself would not be binding to 443 in that setup.

📝 Note: If journalctl output appears truncated with > at the end of lines, the --no-pager flag ensures the full text is printed without being cut off at the terminal width.

✅ Solution

Re-apply the CAP_NET_BIND_SERVICE capability to the Mattermost binary, then restart the service. Because apt replaces the binary on every upgrade, this step must be repeated after each future Mattermost upgrade before restarting the service.

Step 1 — Re-apply the CAP_NET_BIND_SERVICE capability

Run the following command on the Mattermost server as root or with sudo:

sudo setcap CAP_NET_BIND_SERVICE=+eip /opt/mattermost/bin/mattermost

⚠️ Important: This command only adds a capability to the Mattermost binary. It does not modify configuration files or affect any other process. The capability will be lost again the next time apt replaces the binary during an upgrade.

Step 2 — Restart the Mattermost Service

sudo systemctl restart mattermost

Step 3 — Verify the Service is Running

sudo systemctl status mattermost

The service should show as active (running). You can also confirm the version reflects the upgrade by clicking the grid icon (Product menu) in the top-left of the Mattermost UI and selecting About Mattermost.