alibaba/spring-ai-alibaba · error · BizException

TOOL_PARAMS_INVALID

TOOL_PARAMS_INVALID

Error message

TOOL_PARAMS_INVALID: authorization_position (position must be header or query)

What it means

TOOL_PARAMS_INVALID with parameter 'authorization_position' is thrown by ToolExecutionServiceImpl.callOpenApi when a plugin's authorization is configured with a Plugin.AuthorizationPosition value that is neither HEADER nor QUERY. Only those two positions are supported for placing credentials on the outgoing HTTP request.

Source

Thrown at spring-ai-alibaba-admin/spring-ai-alibaba-admin-server-core/src/main/java/com/alibaba/cloud/ai/studio/core/base/service/impl/ToolExecutionServiceImpl.java:146

			// populate auth info to either header or query
			if (pluginConfig.getAuth() != null && pluginConfig.getAuth().getType() != Plugin.ApiAuthType.NONE) {
				Plugin.ApiAuth auth = pluginConfig.getAuth();
				Plugin.AuthorizationType authType = auth.getAuthorizationType();
				if (authType == Plugin.AuthorizationType.BEARER) {
					headers.put(HttpHeaders.AUTHORIZATION, "Bearer " + auth.getAuthorizationValue());
				}
				else if (authType == Plugin.AuthorizationType.BASIC) {
					headers.put(HttpHeaders.AUTHORIZATION, "Basic " + auth.getAuthorizationValue());
				}
				else if (authType == Plugin.AuthorizationType.CUSTOM) {
					if (auth.getAuthorizationPosition() == Plugin.AuthorizationPosition.HEADER) {
						headers.put(auth.getAuthorizationKey(), auth.getAuthorizationValue());
					}
					else if (auth.getAuthorizationPosition() == Plugin.AuthorizationPosition.QUERY) {
						queryParameters.put(auth.getAuthorizationKey(), auth.getAuthorizationValue());
					}
					else {
						throw new BizException(ErrorCode.TOOL_PARAMS_INVALID.toError("authorization_position",
								"position must be header or query"));
					}
				}
				else {
					throw new BizException(ErrorCode.TOOL_PARAMS_INVALID.toError("authorization_type",
							"type must be basic, bearer or custom"));
				}
			}

			// populate input params to header, path, query or body
			List<ApiParameter> apiParameters = toolConfig.getInputParams();
			Map<String, Object> paramValues = request.getArguments();
			for (ApiParameter apiParameter : apiParameters) {
				ApiParameterLocation location = ApiParameterLocation
					.of(StringUtils.lowerCase(apiParameter.getLocation()));
				if (location == null) {
					continue;
				}

View on GitHub (pinned to f82da0b50f)

Solutions

1. Set the plugin's authorization position to 'header' or 'query' in the plugin configuration UI.
2. Inspect the stored plugin JSON and fix the authorizationPosition field to a supported value.
3. Re-create the plugin with valid auth config if the stored enum is corrupt.
4. If you need another position (e.g. cookie), it is unsupported — migrate auth to header/query.

Example fix

// before (plugin config JSON)
{"authorization": {"type": "bearer", "position": "cookie"}}
// after
{"authorization": {"type": "bearer", "position": "header"}}

Plugin.AuthorizationPosition pos = plugin.getAuthorization().getAuthorizationPosition();
if (pos != Plugin.AuthorizationPosition.HEADER && pos != Plugin.AuthorizationPosition.QUERY) {
    throw new IllegalArgumentException("authorization position must be header or query");
}

boolean hasValidAuthPosition(Plugin p) {
    Plugin.AuthorizationPosition pos = p.getAuthorization().getAuthorizationPosition();
    return pos == Plugin.AuthorizationPosition.HEADER || pos == Plugin.AuthorizationPosition.QUERY;
}

try {
    toolExecutionService.executeTool(request);
} catch (BizException e) {
    if (e.getMessage().contains("authorization_position")) {
        // fix the plugin auth config and re-run
    }
    throw e;
}

When it happens

Trigger: A plugin's auth configuration persisted an unknown/legacy AuthorizationPosition enum value; deserialization produced a value outside the handled enum set; the config JSON contains a position string that maps to no supported case.

Common situations: Manually editing plugin config in the database and entering an invalid position; version upgrade where an old enum constant is no longer handled; importing a plugin export from another version with a different enum set.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• BuildToolSchemaError
• INVALID_PARAMS
• Param Not Support Object
• Param Not Support Array<Object>
• RequestBody Only Support object Type

AI-assisted analysis of alibaba/spring-ai-alibaba@f82da0b50f (2026-09-09). Data as JSON: /api/errors/81034d7fe1c96be0. Report an issue: GitHub.