What causes "no binaries available to link" in gravitational/teleport?

Re-download/re-stage the target version so the package's bin directory is populated.

no binaries available to link

Error message

no binaries available to link

What it means

ErrNoBinaries is returned by the autoupdate agent's link logic (forceLinks, tryLinks, and the local installer) when there are no binaries available to link into the target install directory. It surfaces when the staged package's binary directory is missing/empty or when zero binaries were successfully linked, causing the operation to revert.

Source

Thrown at lib/autoupdate/agent/updater.go:350

	UnlinkSystem(ctx context.Context) error
	// List the installed revisions of Teleport.
	List(ctx context.Context) (revisions []Revision, err error)
	// Remove the Teleport agent at revision.
	// Remove must be idempotent.
	Remove(ctx context.Context, rev Revision) error
	// IsLinked returns true if the revision is linked to path.
	IsLinked(ctx context.Context, rev Revision, pathDir string) (bool, error)
}

var (
	// ErrLinked is returned when a linked version cannot be operated on.
	ErrLinked = errors.New("version is linked")
	// ErrNotSupported is returned when the operation is not supported on the platform.
	ErrNotSupported = errors.New("not supported on this platform")
	// ErrNotAvailable is returned when the operation is not available at the current version of the platform.
	ErrNotAvailable = errors.New("not available at this version")
	// ErrNoBinaries is returned when no binaries are available to be linked.
	ErrNoBinaries = errors.New("no binaries available to link")
	// ErrFilePresent is returned when a file is present.
	ErrFilePresent = errors.New("file present")
	// ErrNotInstalled is returned when Teleport is not installed.
	ErrNotInstalled = errors.New("not installed")
)

// Process provides an API for interacting with a running Teleport process.
type Process interface {
	// Name of the process.
	Name() string
	// Reload must reload the Teleport process as gracefully as possible.
	// If the process is not healthy after reloading, Reload must return an error.
	// If the process did not require reloading, Reload must return ErrNotNeeded.
	// E.g., if the process is not enabled, or it was already reloaded after the last Sync.
	// If the type implementing Process does not support the system process manager,
	// Reload must return ErrNotSupported.
	Reload(ctx context.Context) error
	// Sync must validate and synchronize process configuration.

View on GitHub (pinned to 1283425b60)

Solutions

Re-download/re-stage the target version so the package's bin directory is populated.
Verify the staged directory exists and contains binaries: check the versions dir under the agent's package root for a bin/ folder.
Ensure the downloaded package matches the host architecture/OS (wrong-arch packages may extract without usable binaries).
Retry the link operation; the installer reverts state on this error so a clean retry is safe.

Example fix

// before
revert, err := installer.tryLink(ctx)
if err != nil {
    return err
}
// after
revert, err := installer.tryLink(ctx)
if err != nil {
    if errors.Is(err, autoupdate.ErrNoBinaries) {
        log.WarnContext(ctx, "no binaries staged; re-fetching package")
        _ = installer.fetchPackage(ctx, targetVersion) // re-stage then retry
    }
    return trace.Wrap(err)
}

Defensive patterns

Strategy: retry

Validate before calling

entries, err := os.ReadDir(filepath.Join(stageDir, "bin"))
if os.IsNotExist(err) || len(entries) == 0 {
    // re-stage package before attempting link
}

Type guard

func IsNoBinaries(err error) bool { return errors.Is(err, autoupdate.ErrNoBinaries) }

Try / catch

revert, err := installer.tryLink(ctx)
if errors.Is(err, autoupdate.ErrNoBinaries) {
    _ = revert(ctx)
    _ = installer.fetchPackage(ctx, targetVersion) // re-stage and retry once
}

Prevention

Verify staged package integrity (bin/ populated) before linking
Match package architecture to host arch when downloading
Avoid deleting staging directories while installs are in progress

When it happens

Trigger: installer.go:752 — os.ReadDir(srcBinDir) returns os.ErrNotExist (staged version directory has no bin dir); installer.go:798 — the link loop completed but linked == 0 binaries.

Common situations: A corrupted or partially-downloaded staged package (version directory extracted without binaries); pointing the updater at a package variant with no binaries for the architecture; cleaning up staging dirs while an install is in flight.

Related errors

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