gravitational/teleport · info

baseURL is not defined

Error message

baseURL is not defined

What it means

ErrNoBaseURL indicates that managed (self-)updates of client tools cannot proceed because TELEPORT_CDN_BASE_URL is not set. When updates are centrally managed, the CDN base URL must be provided via that environment variable; without it the updater cannot construct download URLs. Callers intentionally ignore this error to fall back to executing the current tools version.

Source

Thrown at lib/autoupdate/tools/utils.go:50

	"strings"
	"time"

	"github.com/coreos/go-semver/semver"
	"github.com/gravitational/trace"

	"github.com/gravitational/teleport/api/constants"
	"github.com/gravitational/teleport/api/types"
	"github.com/gravitational/teleport/lib/automaticupgrades/version"
	"github.com/gravitational/teleport/lib/autoupdate"
	"github.com/gravitational/teleport/lib/modules"
	"github.com/gravitational/teleport/lib/utils"
	"github.com/gravitational/teleport/lib/utils/packaging"
)

var (
	// ErrNoBaseURL is returned when `TELEPORT_CDN_BASE_URL` must be set
	// in order to proceed with managed updates.
	ErrNoBaseURL = errors.New("baseURL is not defined")
	// ErrVersionCheck is returned when the downloaded version fails
	// to execute for version identification.
	ErrVersionCheck = errors.New("version check failed")
)

// Dir returns the client tools installation directory path, using the following fallback order:
// $TELEPORT_TOOLS_DIR, $TELEPORT_HOME/bin, and $HOME/.tsh/bin.
func Dir() (string, error) {
	toolsDir := os.Getenv(teleportToolsDirsEnv)
	if toolsDir == "" {
		toolsDir = os.Getenv(types.HomeEnvVar)
		if toolsDir == "" {
			var err error
			toolsDir, err = os.UserHomeDir()
			if err != nil {
				return "", trace.Wrap(err)
			}
			toolsDir = filepath.Join(toolsDir, ".tsh", "bin")

View on GitHub (pinned to 1283425b60)

Solutions

1. Set TELEPORT_CDN_BASE_URL to your managed CDN base URL in the environment (shell profile, systemd unit, or CI config).
2. If managed updates are not intended, ignore the error (as helper.go does) and continue with the current binary.
3. Verify with `printenv TELEPORT_CDN_BASE_URL` that the variable reaches the process running the update check.
4. Confirm the update policy/feature flags match your deployment (managed vs public CDN).

Example fix

// before
err := updater.Update(ctxUpdate, resp.Version) // fails: baseURL is not defined
// after
export TELEPORT_CDN_BASE_URL=https://cdn.example.com/teleport
// or, in the caller:
if err := updater.Update(ctxUpdate, resp.Version); err != nil && !errors.Is(err, ErrNoBaseURL) {
    return trace.Wrap(err)
}

if os.Getenv("TELEPORT_CDN_BASE_URL") == "" {
    // managed updates disabled; skip update path or set the variable
}

func IsNoBaseURL(err error) bool { return errors.Is(err, tools.ErrNoBaseURL) }

err := updater.Update(ctxUpdate, v)
if err != nil && !errors.Is(err, context.Canceled) && !errors.Is(err, ErrNoBaseURL) {
    return trace.Wrap(err)
}
// ErrNoBaseURL: continue executing the current tools version

When it happens

Trigger: updateAndReExec / DownloadUpdate / teleportPackageURLs invoked during a tools update check while TELEPORT_CDN_BASE_URL is unset; helper.go:219 and helper.go:234 treat it as a non-fatal skip of the update path.

Common situations: Enterprise/managed deployments where the CDN base URL env var was not propagated to the shell, systemd unit, or CI job; users upgrading from unmanaged (public CDN) builds where the variable is unnecessary.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

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

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