gravitational/teleport · warning

updater config file not found

Error message

updater config file not found

What it means

ErrConfigNotFound is the sentinel returned by findConfigFile (and consumers like HellorUpdaterInfo/StableExecutable paths) when the Teleport updater's update.yaml cannot be located. findConfigFile derives the config location from the running executable's path: it must live under an installation whose binary is four directories below the install root (i.e. under .../versions/... of a managed install). If TELEPORT_UPDATE_CONFIG_FILE is unset and the binary layout does not match a managed install, no update.yaml path exists and this error is wrapped.

Source

Thrown at lib/autoupdate/agent/integrations.go:37

package agent

import (
	"context"
	"errors"
	"io/fs"
	"log/slog"
	"os"
	"path/filepath"

	"github.com/google/uuid"
	"github.com/gravitational/trace"

	"github.com/gravitational/teleport/api/types"
)

var (
	// ErrConfigNotFound is returned by HellorUpdaterInfo when the updater config file cannot be found.
	ErrConfigNotFound = errors.New("updater config file not found")

	// ErrUnstableExecutable is returned by StableExecutable when no stable path can be found.
	ErrUnstableExecutable = errors.New("executable has unstable path")
)

const updateConfigFileEnvVar = "TELEPORT_UPDATE_CONFIG_FILE"

// IsManagedByUpdater returns true if the local Teleport binary is managed by teleport-update.
// Note that true may be returned even if auto-updates is disabled or the version is pinned.
// The binary is considered managed if it lives under /opt/teleport, but not within the package
// path at /opt/teleport/system.
func IsManagedByUpdater() (bool, error) {
	systemd, err := hasSystemD()
	if err != nil {
		return false, trace.Wrap(err)
	}
	if !systemd {
		return false, nil

View on GitHub (pinned to 1283425b60)

Solutions

1. If this is a Kubernetes upgrader, treat it as expected: the service skips updater info when errors.Is(err, ErrConfigNotFound) — verify you are on a chart version that does this.
2. Set TELEPORT_UPDATE_CONFIG_FILE to the absolute path of update.yaml if your install layout is non-standard.
3. Reinstall via an updater-managed layout (binary under <install>/versions/...) so findParentMatching can locate the config.
4. Check that the running binary path is the managed install path, not a copied/symlinked binary elsewhere.

Example fix

// before: binary outside managed layout, no config found
$ TELEPORT_UPDATE_CONFIG_FILE= ./teleport version
// after: point at the config explicitly
$ export TELEPORT_UPDATE_CONFIG_FILE=/opt/teleport/update.yaml

// Detect the condition before it is wrapped:
_, err := os.Stat("/opt/teleport/update.yaml")
hasConfig := err == nil
// Or set the env var for non-standard layouts:
os.Setenv("TELEPORT_UPDATE_CONFIG_FILE", "/path/to/update.yaml")

func isConfigNotFound(err error) bool { return errors.Is(err, autoupdate.ErrConfigNotFound) }

info, err := autoupdate.ReadHelloUpdaterInfo(ctx, log, hostUUID)
if errors.Is(err, autoupdate.ErrConfigNotFound) {
    // no updater config: treat as unmanaged (see lib/service/service.go:1456)
    return hello, nil
} else if err != nil {
    return trace.Wrap(err)
}

When it happens

Trigger: Calling ReadHelloUpdaterInfo (or anything calling findConfigFile) when: (1) TELEPORT_UPDATE_CONFIG_FILE is not set, (2) os.Executable() is not under a .../<parent>/versions/<dir>/ layout matching findParentMatching(path, versionsDirName, 4), so the function returns trace.Wrap(ErrConfigNotFound) at integrations.go:158.

Common situations: Kubernetes (kube controller) upgraders on older chart versions where no update.yaml is deployed — expected and handled at lib/service/service.go:1456; Teleport installed from a tarball or manually placed outside /opt/teleport's versions layout; custom install paths that break the versions-dir convention.

Understand the failure class

Background: "Config file not found": what it means and how to fix it in docker-sync, Maven, Vagrant, Turborepo and other tools — this error's family across 60 libraries.

Related errors

• executable has unstable path
• version is linked
• not supported on this platform
• no binaries available to link
• file present

AI-assisted analysis of gravitational/teleport@1283425b60 (2026-09-02). Data as JSON: /api/errors/c134c224d6992591. Report an issue: GitHub.