---
title: Troubleshoot installation and startup
description: 'Resolve Telegraf Controller installation and startup problems: port conflicts, permission errors, the macOS quarantine attribute, and unreachable ports.'
url: https://docs.influxdata.com/telegraf/controller/admin/troubleshoot/installation/
estimated_tokens: 846
publisher: InfluxData
canonical: https://docs.influxdata.com/telegraf/controller/admin/troubleshoot/installation/
date: '2026-09-22T08:51:42-06:00'
lastmod: '2026-09-22T08:51:42-06:00'
---

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

* [Port already in use](#port-already-in-use)
* [Permission denied (Linux/macOS)](#permission-denied-linuxmacos)
* [Ports are not reachable](#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:

|         Description         |Environment Variable|   Command Flag   |
|-----------------------------|--------------------|------------------|
|    Web Interface and API    |     `APP_PORT`     |     `--port`     |
|Web Interface (separate port)|     `UI_PORT`      |   `--ui-port`    |
|      Heartbeat server       |  `HEARTBEAT_PORT`  |`--heartbeat-port`|

*For more information, see the[General section of the configuration options reference](/telegraf/controller/reference/config-options/#general).*

[Use Environment Variables](#use-environment-variables)[Use Command Flags](#use-command-flags)

[Linux/macOS](#linuxmacos)[Windows (Powershell)](#windows-powershell)

```sh
APP_PORT=3000
HEARTBEAT_PORT=3001

telegraf_controller
```

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

./telegraf_controller.exe
```

[Linux/macOS](#linuxmacos-2)[Windows (Powershell)](#windows-powershell-2)

```sh
telegraf_controller --port=3000 --heartbeat-port=3001
```

```powershell
./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:

```sh
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

```bash
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`](/telegraf/controller/reference/config-options/#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](/telegraf/controller/admin/networking/).

#### Related

* [Install Telegraf Controller](/telegraf/controller/install/)
* [Networking and ports](/telegraf/controller/admin/networking/)
* [Telegraf Controller configuration options](/telegraf/controller/reference/config-options/)
| Description | Environment Variable | Command Flag |
| --- | --- | --- |
| Description | Environment Variable | Command Flag |
| Web Interface and API | APP_PORT | --port |
| Web Interface (separate port) | UI_PORT | --ui-port |
| Heartbeat server | HEARTBEAT_PORT | --heartbeat-port |