---
title: Troubleshoot Telegraf Controller
description: 'Find the fix for a Telegraf Controller problem by symptom: startup failures, port conflicts, rejected agent heartbeats, TLS errors, and database errors.'
url: https://docs.influxdata.com/telegraf/controller/admin/troubleshoot/
estimated_tokens: 779
publisher: InfluxData
canonical: https://docs.influxdata.com/telegraf/controller/admin/troubleshoot/
date: '2026-09-23T16:27:16-06:00'
lastmod: '2026-09-23T16:27:16-06:00'
---

Find the fix for a Telegraf Controller problem by its symptom.
Symptoms appear in the server log output, in agent logs, or as errors in the
web interface.
For the log messages worth alerting on before they become problems, see[Monitor Telegraf Controller](/telegraf/controller/admin/monitor/).

## Find your symptom

* **`address already in use` at startup**: another process holds one of the
  server’s ports.
  See [Port already in use](/telegraf/controller/admin/troubleshoot/installation/#port-already-in-use).
* **`Permission denied` when running the binary, or macOS blocks the
  executable**: the file is not executable, or the macOS quarantine
  attribute blocks it.
  See [Permission denied](/telegraf/controller/admin/troubleshoot/installation/#permission-denied-linuxmacos).
* **Browsers or agents cannot connect to a running server**: a firewall
  blocks the server’s ports.
  See [Ports are not reachable](/telegraf/controller/admin/troubleshoot/installation/#ports-are-not-reachable).
* **Agent heartbeats return `401 Invalid token`**: the heartbeat service
  cannot validate tokens, often because its token cache cannot load.
  See [Agent heartbeats return 401 Invalid token](/telegraf/controller/admin/troubleshoot/agents/#agent-heartbeats-return-401-invalid-token).
* **Agents log `x509: certificate signed by unknown authority`**: agents do
  not trust the server’s TLS certificate.
  See [Agents do not trust the server certificate](/telegraf/controller/admin/troubleshoot/agents/#agents-do-not-trust-the-server-certificate).
* **`database is locked`, `database or disk is full`, or `database disk image is malformed` in the log**: SQLite lock contention, disk
  exhaustion, or corruption.
  See [Identify the failure type](/telegraf/controller/admin/troubleshoot/database/#identify-the-failure-type).
* **The server cannot connect to PostgreSQL, or logs `error performing TLS handshake`**: a connection string, network, or certificate trust problem.
  See [PostgreSQL](/telegraf/controller/admin/troubleshoot/database/#postgresql).
* **License errors**: a missing, expiring, or expired Telegraf Enterprise
  license.
  See [Troubleshoot licensing](/telegraf/controller/telegraf-enterprise/troubleshoot/).

## [Installation and startup](/telegraf/controller/admin/troubleshoot/installation/)

Resolve Telegraf Controller installation and startup problems: port conflicts, permission errors, the macOS quarantine attribute, and unreachable ports.

## [Agent heartbeats and tokens](/telegraf/controller/admin/troubleshoot/agents/)

Diagnose rejected Telegraf agent heartbeats, including 401 Invalid token responses caused by token cache and database TLS failures, and agents that do not trust the server certificate.

## [Database](/telegraf/controller/admin/troubleshoot/database/)

Identify and repair Telegraf Controller database problems, including connection failures, lock contention, and database corruption.

#### Related

* [Monitor Telegraf Controller](/telegraf/controller/admin/monitor/)
* [Telegraf Controller configuration options](/telegraf/controller/reference/config-options/)