Hive JWT authentication requires jwt or the JWT environment

Error message

Hive JWT authentication requires jwt or the JWT environment variable

What it means

When the auth scheme is JWT, the driver requires a JWT credential: either the jwt connection parameter or the JWT environment variable. If config.Auth is "JWT" (case-insensitive) and config.JWT is empty, applyAuthParameters returns this error, since JWT auth cannot proceed without a token.

Source

Thrown at agents/drivers/argo-go/config.go:580

	config.BrowserToken = firstNonEmpty(parameter(values, "browsertoken"), parameter(values, "token"))
	config.BrowserClientID = parameter(values, "browserclientidentifier")
	if value := parameter(values, "browserresponseport"); value != "" {
		parsed, err := strconv.Atoi(value)
		if err != nil || parsed < 0 || parsed > 65535 {
			return fmt.Errorf("invalid Hive browserResponsePort %q: expected 0-65535", value)
		}
		config.BrowserResponsePort = parsed
	}
	if value := parameter(values, "browserresponsetimeout"); value != "" {
		parsed, err := strconv.ParseInt(value, 10, 64)
		if err != nil || parsed <= 0 {
			return fmt.Errorf("invalid Hive browserResponseTimeout %q: expected positive seconds", value)
		}
		config.BrowserResponseTimeout = time.Duration(parsed) * time.Second
	}
	config.BrowserDisableSSLCheck = parameterBool(values, "browserdisablesslcheck")
	if strings.EqualFold(config.Auth, "JWT") && config.JWT == "" {
		return errors.New("Hive JWT authentication requires jwt or the JWT environment variable")
	}
	if value := parameter(values, "fetchsize"); value != "" {
		parsed, err := strconv.Atoi(value)
		if err != nil || parsed <= 0 {
			return fmt.Errorf("invalid Hive fetchSize %q: expected a positive integer", value)
		}
		config.FetchSize = parsed
	}
	if value := parameter(values, "sockettimeout"); value != "" {
		parsed, err := strconv.ParseInt(value, 10, 64)
		if err != nil {
			return fmt.Errorf("invalid Hive socketTimeout %q: expected seconds", value)
		}
		if parsed > 0 {
			config.SocketTimeout = time.Duration(parsed) * time.Second
		}
	}
	if value := parameter(values, "thrift.client.max.message.size"); value != "" {

View on GitHub (pinned to c0390bff16)

Solutions

Add jwt=<token> to the connection parameters
Set the JWT environment variable expected by the driver before running
Switch auth to a scheme you can satisfy (e.g. NONE, LDAP, DELEGATIONTOKEN) if JWT credentials are unavailable

Example fix

// before
jdbc:hive2://host:10000/default?auth=JWT
// after
jdbc:hive2://host:10000/default?auth=JWT&jwt=<token>

Defensive patterns

Strategy: validation

Validate before calling

if strings.EqualFold(auth, "JWT") && jwtParam == "" && os.Getenv("JWT") == "" {
    return errors.New("JWT auth selected but no token provided")
}

Try / catch

cfg, err := buildConnectionConfig(params)
if err != nil {
    if strings.Contains(err.Error(), "JWT authentication requires") { /* prompt for token */ }
    return err
}

Prevention

When using auth=JWT, always set jwt=... or export the JWT env var in the runtime environment
Check secret mounting in containers/CI — an empty secret silently breaks JWT auth
Use a preflight config validator that checks required params per auth scheme

When it happens

Trigger: Building a connection with auth=JWT in the connection string/parameters but omitting the jwt parameter and the JWT environment variable.

Common situations: Setting auth=JWT copied from a sample but forgetting the token; the JWT env var not exported in the deployment environment (container/CI); token passed under a wrong parameter name.

Understand the failure class

Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

AI-assisted analysis of t8y2/dbx@c0390bff16 (2026-09-05). Data as JSON: /api/errors/f861bcdd91906f2e. Report an issue: GitHub.