{"record":{"id":"495f732029f97eb3","repo":"gravitational/teleport","slug":"file-present","errorCode":null,"errorMessage":"file present","messagePattern":"file present","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"lib/autoupdate/agent/updater.go","lineNumber":352,"sourceCode":"\tList(ctx context.Context) (revisions []Revision, err error)\n\t// Remove the Teleport agent at revision.\n\t// Remove must be idempotent.\n\tRemove(ctx context.Context, rev Revision) error\n\t// IsLinked returns true if the revision is linked to path.\n\tIsLinked(ctx context.Context, rev Revision, pathDir string) (bool, error)\n}\n\nvar (\n\t// ErrLinked is returned when a linked version cannot be operated on.\n\tErrLinked = errors.New(\"version is linked\")\n\t// ErrNotSupported is returned when the operation is not supported on the platform.\n\tErrNotSupported = errors.New(\"not supported on this platform\")\n\t// ErrNotAvailable is returned when the operation is not available at the current version of the platform.\n\tErrNotAvailable = errors.New(\"not available at this version\")\n\t// ErrNoBinaries is returned when no binaries are available to be linked.\n\tErrNoBinaries = errors.New(\"no binaries available to link\")\n\t// ErrFilePresent is returned when a file is present.\n\tErrFilePresent = errors.New(\"file present\")\n\t// ErrNotInstalled is returned when Teleport is not installed.\n\tErrNotInstalled = errors.New(\"not installed\")\n)\n\n// Process provides an API for interacting with a running Teleport process.\ntype Process interface {\n\t// Name of the process.\n\tName() string\n\t// Reload must reload the Teleport process as gracefully as possible.\n\t// If the process is not healthy after reloading, Reload must return an error.\n\t// If the process did not require reloading, Reload must return ErrNotNeeded.\n\t// E.g., if the process is not enabled, or it was already reloaded after the last Sync.\n\t// If the type implementing Process does not support the system process manager,\n\t// Reload must return ErrNotSupported.\n\tReload(ctx context.Context) error\n\t// Sync must validate and synchronize process configuration.\n\t// After the linked Teleport installation is changed, failure to call Sync without\n\t// error before Reload may result in undefined behavior.","sourceCodeStart":334,"sourceCodeEnd":370,"githubUrl":"https://github.com/gravitational/teleport/blob/1283425b60ec5f60d509ba4c791183d452923ff7/lib/autoupdate/agent/updater.go#L334-L370","documentation":"ErrFilePresent signals that the updater refuses to replace a file at the target path because it belongs to a non-linked (independently installed) Teleport, and the operation was not run with force. It is a safety guard against clobbering a manually installed binary. The wrap message includes the refused path, e.g. 'refusing to replace file at /usr/local/bin/teleport'.","triggerScenarios":"installer.go:848 — during link/upgrade, os.Link-style replacement hits an existing target that is not part of the linked install and force is not set; installer.go:1066 — rename fails with EEXIST/EINVAL indicating the target file already exists unmanaged.","commonSituations":"A Teleport binary was installed via a system package (deb/rpm) or copied manually to /usr/local/bin, and teleport-update then tries to manage the same path; mixing install methods (package manager + teleport-update) on one host.","solutions":["Remove the non-linked binary at the reported path (or uninstall the deb/rpm package) so teleport-update can manage it.","Re-run the operation with the force flag if you intentionally want to replace the existing file.","Verify ownership of the conflicting file (`ls -l <path>`) and confirm it is not needed before forcing.","Standardize on one install method per host to avoid recurrence."],"exampleFix":"// before\n_, err := installer.link(ctx, target) // fails: refusing to replace file at /usr/bin/teleport\n// after\n// remove the unmanaged install first\n// $ sudo apt-get remove teleport  (or delete /usr/bin/teleport)\n_, err := installer.link(ctx, target) // succeeds","handlingStrategy":"validation","validationCode":"if _, err := os.Lstat(newname); err == nil {\n    // target exists: confirm it belongs to a linked install or plan removal/force\n}","typeGuard":"func IsFilePresent(err error) bool { return errors.Is(err, autoupdate.ErrFilePresent) }","tryCatchPattern":"if _, err := installer.link(ctx, target); err != nil {\n    if errors.Is(err, autoupdate.ErrFilePresent) {\n        return fmt.Errorf(\"unmanaged install at %s; remove it or use force\", target)\n    }\n    return trace.Wrap(err)\n}","preventionTips":["Use one install method per host (package manager OR teleport-update, not both)","Check for pre-existing binaries in target paths before enabling autoupdate","Read the wrapped path in the error message ('refusing to replace file at ...') to locate the conflict"],"tags":["file-conflict","autoupdate","install-management","sentinel-error"],"backgroundTag":"file-already-exists","analyzedSha":"1283425b60ec5f60d509ba4c791183d452923ff7","analyzedAt":"2026-09-02T04:06:41.601Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T05:18:18.240Z"}