alibaba/spring-ai-alibaba · error · IllegalArgumentException

Elastic search index name must be provided

Error message

Elastic search index name must be provided

What it means

ElasticSearchVectorStoreService.createIndex() requires a non-blank index name from the supplied IndexConfig; if name is null/empty/whitespace it throws IllegalArgumentException before any Elasticsearch call is made. This is a fail-fast required-argument check.

Source

Thrown at spring-ai-alibaba-admin/spring-ai-alibaba-admin-server-core/src/main/java/com/alibaba/cloud/ai/studio/core/rag/vectorstore/elasticsearch/ElasticSearchVectorStoreService.java:103

	private final FilterExpressionConverter filterExpressionConverter = new ElasticsearchAiSearchFilterExpressionConverter();

	public ElasticSearchVectorStoreService(ModelFactory modelFactory, ElasticsearchClient elasticsearchClient,
			RestClient restClient) {
		this.modelFactory = modelFactory;
		this.elasticsearchClient = elasticsearchClient;
		this.restClient = restClient;
	}

	/**
	 * Creates a new Elasticsearch index with vector search capabilities
	 * @param indexConfig Configuration for the index including name and embedding model
	 */
	@Override
	public void createIndex(IndexConfig indexConfig) {
		String indexName = indexConfig.getName();

		if (StringUtils.isBlank(indexName)) {
			throw new IllegalArgumentException("Elastic search index name must be provided");
		}

		ElasticsearchVectorStoreOptions options = new ElasticsearchVectorStoreOptions();
		options.setIndexName(indexName);
		options.setSimilarity(SimilarityFunction.dot_product);

		String similarityAlgo = SimilarityFunction.cosine.name();
		IndexSettings indexSettings = IndexSettings
			.of(settings -> settings.numberOfShards(String.valueOf(1)).numberOfReplicas(String.valueOf(1)));

		// Maybe using json directly?
		int dimension = EmbeddingModelDimension.getDimension(indexConfig.getEmbeddingModel(), DEFAULT_DIMENSION);
		Map<String, Property> properties = new HashMap<>();
		properties.put(RagConstants.VECTOR_FIELD, Property.of(property -> property.denseVector(
				DenseVectorProperty.of(dense -> dense.index(true).dims(dimension).similarity(similarityAlgo)))));
		properties.put(RagConstants.TEXT_FIELD, Property.of(property -> property.text(TextProperty.of(t -> t))));

		Map<String, Property> metadata = new HashMap<>();

View on GitHub (pinned to f82da0b50f)

Solutions

1. Set a valid index name: indexConfig.setName("kb-...") before calling createIndex
2. Validate the name with StringUtils.isBlank at the caller before invoking createIndex
3. Ensure the knowledge base record supplying the name is populated and not blank

Example fix

// before
IndexConfig cfg = new IndexConfig();
store.createIndex(cfg);
// after
IndexConfig cfg = new IndexConfig();
cfg.setName("my-knowledge-base");
if (StringUtils.isBlank(cfg.getName())) throw new IllegalStateException("index name required");
store.createIndex(cfg);

if (indexConfig == null || StringUtils.isBlank(indexConfig.getName())) {
    throw new IllegalArgumentException("createIndex requires a non-blank index name");
}

try {
    store.createIndex(indexConfig);
} catch (IllegalArgumentException e) {
    log.error("Index config invalid: {}", e.getMessage());
}

When it happens

Trigger: Calling createIndex() with an IndexConfig whose name was never set, or set to "" or " ".

Common situations: Building IndexConfig programmatically and forgetting setName(); reading a knowledge-base name from config/DB that is empty; trimming user input down to nothing.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• INVALID_PARAMS
• regex cannot be empty
• failed to create index
• Param Not Support Object
• Param Not Support Array<Object>

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