---
title: Troubleshoot Telegraf Controller installation
description: Resolve common installation and startup issues with Telegraf Controller.
url: https://docs.influxdata.com/telegraf/controller/install/troubleshoot/
estimated_tokens: 1022
publisher: InfluxData
canonical: https://docs.influxdata.com/telegraf/controller/install/troubleshoot/
date: '2026-07-01T07:10:10-07:00'
lastmod: '2026-07-01T07:10:10-07:00'
---

Resolve common installation and startup issues with Telegraf Controller.
Check the symptoms below and apply the recommended fix before continuing with
configuration.

* [Port Already in Use](#port-already-in-use)
* [Permission Denied (Linux/macOS)](#permission-denied-linuxmacos)
* [Database Connection Issues](#database-connection-issues)
* [Firewall Configuration](#firewall-configuration)
* [Security Considerations](#security-considerations)

## 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 ####

#### Linux/macOS ####

```sh
APP_PORT=3000
HEARTBEAT_PORT=3001

telegraf_controller
```

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

./telegraf_controller.exe
```

#### Linux/macOS ####

```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**.

## Database connection issues

If there are database connection issues, check the following depending on which
database you’re using:

### SQLite

* Check file permissions for SQLite database directory

### PostgreSQL

* Ensure PostgreSQL is running
* Check the format of and credentials in your data source name (DSN or database URL)
* Verify network connectivity

## Firewall configuration

Ensure the following ports are open in your network Firewall configuration:

* **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)

## Security considerations

* **SSL/TLS**: Set the [`SSL_CERT_PATH` and `SSL_KEY_PATH`](/telegraf/controller/reference/config-options/#tls)environment variables for production deployments. If agents log`x509: certificate signed by unknown authority`, they do not trust the
  certificate. See[Secure Telegraf Controller with TLS](/telegraf/controller/install/secure-tls/#trust-the-certificate-on-each-agent).
* **Firewall**: Restrict access to the web interface and heartbeat ports
* **Database Security**:
  * **PostgreSQL**: Use strong passwords
  * **SQLite**: Ensure the database file is protected with restricted permissions
    (`chmod 600`)

#### Related

* [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 |