Troubleshoot installation and startup

Resolve problems that keep Telegraf Controller from starting or from being reached after installation.

• Port already in use
• Permission denied (Linux/macOS)
• Ports are not reachable

Port already in use

If the default ports (8888 and 8000) are already in use, use the following configuration options to specify alternative ports:

For more information, see the General section of the configuration options reference.

APP_PORT=3000
HEARTBEAT_PORT=3001

telegraf_controller

$env:APP_PORT=3000
$env:HEARTBEAT_PORT=3001

./telegraf_controller.exe

telegraf_controller --port=3000 --heartbeat-port=3001

./telegraf_controller.exe --port=3000 --heartbeat-port=3001

Permission denied (Linux/macOS)

If you do not have permission to run the telegraf_controller executable, ensure the file has executable permissions:

chmod +x telegraf_controller

macOS: Remove the quarantine attribute

macOS places a quarantine attribute on executable files downloaded from a browser and restricts file execution. To remove the quarantine attribute, use Terminal or System Settings.

Remove the quarantine attribute in Terminal

xattr -d com.apple.quarantine telegraf_controller

Remove the quarantine attribute in System Settings

1. Attempt to run the telegraf_controller executable.
2. In macOS, navigate to System Settings > Privacy & Security.
3. Scroll to the bottom of the window.
4. Next to the message about Telegraf Controller, click Allow.

Ports are not reachable

If the server starts but browsers or agents cannot connect, make sure your firewall allows the ports Telegraf Controller listens on:

• Web interface and API: TCP 8888 (or custom port)
• Web interface (separate port): the ui-port value, if configured
• Heartbeat server: TCP 8000 (or custom heartbeat port)

For which clients need access to each port and how to expose them safely, see Networking and ports.