{"record":{"id":"2fa7fef41de2be58","repo":"gravitational/teleport","slug":"version-check-failed","errorCode":null,"errorMessage":"version check failed","messagePattern":"version check failed","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"lib/autoupdate/tools/utils.go","lineNumber":53,"sourceCode":"\t\"github.com/coreos/go-semver/semver\"\n\t\"github.com/gravitational/trace\"\n\n\t\"github.com/gravitational/teleport/api/constants\"\n\t\"github.com/gravitational/teleport/api/types\"\n\t\"github.com/gravitational/teleport/lib/automaticupgrades/version\"\n\t\"github.com/gravitational/teleport/lib/autoupdate\"\n\t\"github.com/gravitational/teleport/lib/modules\"\n\t\"github.com/gravitational/teleport/lib/utils\"\n\t\"github.com/gravitational/teleport/lib/utils/packaging\"\n)\n\nvar (\n\t// ErrNoBaseURL is returned when `TELEPORT_CDN_BASE_URL` must be set\n\t// in order to proceed with managed updates.\n\tErrNoBaseURL = errors.New(\"baseURL is not defined\")\n\t// ErrVersionCheck is returned when the downloaded version fails\n\t// to execute for version identification.\n\tErrVersionCheck = errors.New(\"version check failed\")\n)\n\n// Dir returns the client tools installation directory path, using the following fallback order:\n// $TELEPORT_TOOLS_DIR, $TELEPORT_HOME/bin, and $HOME/.tsh/bin.\nfunc Dir() (string, error) {\n\ttoolsDir := os.Getenv(teleportToolsDirsEnv)\n\tif toolsDir == \"\" {\n\t\ttoolsDir = os.Getenv(types.HomeEnvVar)\n\t\tif toolsDir == \"\" {\n\t\t\tvar err error\n\t\t\ttoolsDir, err = os.UserHomeDir()\n\t\t\tif err != nil {\n\t\t\t\treturn \"\", trace.Wrap(err)\n\t\t\t}\n\t\t\ttoolsDir = filepath.Join(toolsDir, \".tsh\", \"bin\")\n\t\t} else {\n\t\t\ttoolsDir = filepath.Join(toolsDir, \"bin\")\n\t\t}","sourceCodeStart":35,"sourceCodeEnd":71,"githubUrl":"https://github.com/gravitational/teleport/blob/1283425b60ec5f60d509ba4c791183d452923ff7/lib/autoupdate/tools/utils.go#L35-L71","documentation":"ErrVersionCheck is returned when a downloaded or installed tool binary cannot be executed to determine its version — running the tool to print its version failed or produced unusable output. The updater uses this to treat the installed tools directory as broken and fall back to the local version rather than re-execing into a possibly corrupt binary.","triggerScenarios":"utils.go:123 — executing the tool to identify its version fails or emits unparseable output, so CheckExecutedToolVersion/CheckLocal returns ErrVersionCheck; updater.go:203 — Update() sees this error and returns the local version with ReExec:false instead of switching binaries.","commonSituations":"A truncated or corrupted download in the tools directory; a binary with a broken dynamic-linker dependency (missing shared libraries) that exits nonzero; a stale/incompatible binary from a different architecture.","solutions":["Delete the affected binary (or the whole tools directory, e.g. ~/.tsh/bin) so the updater re-downloads a fresh copy.","Run the tool manually to see the underlying exec failure (`~/.tsh/bin/tsh version`) — missing libs or arch mismatch will show there.","Retry the update; the updater skips the broken version and keeps executing the local one.","Check disk space and download integrity if corruption recurs."],"exampleFix":"// before\ntoolsVersion, err := CheckExecutedToolVersion(u.toolsDir)\nif err != nil {\n    return trace.Wrap(err) // hard failure on broken binary\n}\n// after\nif trace.IsNotFound(err) || errors.Is(err, ErrVersionCheck) {\n    return &UpdateResponse{Version: u.localVersion, ReExec: false}, nil, nil // fall back to local\n}","handlingStrategy":"fallback","validationCode":"out, err := exec.Command(toolPath, \"version\").CombinedOutput()\nif err != nil {\n    // tool binary broken; purge it before updating\n    _ = os.Remove(toolPath)\n}","typeGuard":"func IsVersionCheckFailed(err error) bool { return errors.Is(err, tools.ErrVersionCheck) }","tryCatchPattern":"toolsVersion, err := CheckExecutedToolVersion(u.toolsDir)\nif trace.IsNotFound(err) || errors.Is(err, ErrVersionCheck) {\n    return &UpdateResponse{Version: u.localVersion, ReExec: false}, nil, nil\n}","preventionTips":["Manually run the installed tool's version command to diagnose broken binaries","Remove ~/.tsh/bin (or the tools dir) to force a clean re-download","Check disk space and download integrity to prevent truncation"],"tags":["version-check","corrupt-binary","autoupdate","sentinel-error"],"backgroundTag":"binary-version-check-failed","analyzedSha":"1283425b60ec5f60d509ba4c791183d452923ff7","analyzedAt":"2026-09-02T04:06:41.601Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}