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 Auth is set to JWT, the driver requires the token in the 'jwt' parameter (or the JWT environment variable), because JWT auth has no other credential source. If config.JWT remains empty after parameter and environment resolution, the config is rejected.

Source

Thrown at agents/drivers/hive-go/config.go:583

	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 the jwt parameter with the bearer token to the connection parameters, or set the JWT environment variable the driver reads.
If using a DSN, URL-encode the token into the connection string's jwt property.
Verify the auth value is intentionally JWT; if you meant another mechanism (e.g. LDAP, NONE), change auth accordingly.
Check secret injection (env vars, mounted files) so the token reaches the process at connect time.

Example fix

// before
params := map[string]string{"auth": "JWT"}
// after
params := map[string]string{"auth": "JWT", "jwt": "eyJhbGciOi..."}

Defensive patterns

Strategy: validation

Validate before calling

func requireJWT(params map[string]string) error {
    if strings.EqualFold(params["auth"], "JWT") &&
        params["jwt"] == "" && os.Getenv("JWT") == "" {
        return errors.New("JWT auth requires jwt param or JWT env var")
    }
    return nil
}

Prevention

Inject the token under the exact key 'jwt'
Verify secret presence in deployment readiness checks
When changing auth mode, update the corresponding credential source at the same time

When it happens

Trigger: Setting auth=JWT but forgetting the jwt parameter; the JWT env var unset in the runtime environment; passing the token under a wrong key like 'token' or 'password' instead of 'jwt'.

Common situations: Switching a deployment from NONE/LDAP to JWT auth without updating the secret injection, Kubernetes/Docker env where the JWT secret wasn't mounted, DSN strings that include auth=JWT but the token is sent via headers instead.

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/ef57eae98ca56250. Report an issue: GitHub.