spring-projects/spring-ai · error · IllegalArgumentException

Failed to load default system message suffix from classpath

Error message

Failed to load default system message suffix from classpath resource

What it means

The ToolSearchToolCallingAdvisor.Builder appends a default suffix to the system prompt by reading the classpath resource classpath:/DEFAULT_SYSTEM_PROMPT_SUFFIX.md shipped in the advisor jar. If that resource cannot be found or read, the builder throws this IllegalArgumentException. It essentially always means the jar is corrupted, shaded incorrectly, or the resource was excluded at build time.

Source

Thrown at advisors/spring-ai-tool-search-advisor/src/main/java/org/springframework/ai/chat/client/advisor/toolsearch/ToolSearchToolCallingAdvisor.java:481

		}

		/**
		 * Builds and returns a new ToolSearchToolCallingAdvisor instance with the
		 * configured properties.
		 * @return a new ToolSearchToolCallingAdvisor instance
		 * @throws IllegalArgumentException if required parameters are null or invalid
		 */
		@Override
		public ToolSearchToolCallingAdvisor build() {

			if (!StringUtils.hasText(this.systemMessageSuffix)) {
				try {
					this.systemMessageSuffix = new DefaultResourceLoader()
						.getResource("classpath:/DEFAULT_SYSTEM_PROMPT_SUFFIX.md")
						.getContentAsString(StandardCharsets.UTF_8);
				}
				catch (Exception ex) {
					throw new IllegalArgumentException(
							"Failed to load default system message suffix from classpath resource", ex);
				}
			}

			Assert.notNull(this.toolIndex, "toolIndex is required");
			return new ToolSearchToolCallingAdvisor(getToolCallingManager(), getAdvisorOrder(),
					getToolExecutionEligibilityChecker(), this.toolIndex,
					Objects.requireNonNull(this.systemMessageSuffix), this.referenceToolNameAccumulation,
					this.maxResults, this.isConversationHistoryEnabled(), this.sessionIdKeyName, this.evictionStrategy);
		}

		@Override
		protected ToolCallingAdvisor.Builder<?> newCopy() {
			return new Builder<>();
		}

		@Override
		public ToolCallingAdvisor.Builder<?> copy() {

View on GitHub (pinned to 98a7beda4f)

Solutions

1. Verify the jar contains the file: unzip -l spring-ai-tool-search-advisor-*.jar | grep DEFAULT_SYSTEM_PROMPT_SUFFIX.md; if missing, re-download/repair the dependency.
2. Check your Maven/Gradle build for resource filtering or exclusion rules (e.g. maven-resources-plugin nonFilteredFileExtensions, shading includes) that drop *.md resources.
3. Run mvn clean and rebuild — stale target/classes without copied resources commonly causes this in IDE runs.
4. Disable build plugins (minimizeJar/shrink) that remove 'unused' resources and retry.

Example fix

<!-- before: maven-shade-plugin strips resources -->
<filters><filter><artifact>*:*</artifact><excludes><exclude>*.md</exclude></excludes></filter></filters>

<!-- after -->
<filters><filter><artifact>*:*</artifact><excludes><exclude>META-INF/*.SF</exclude></excludes></filter></filters>

if (new DefaultResourceLoader().getResource("classpath:/DEFAULT_SYSTEM_PROMPT_SUFFIX.md").getContentAsString(StandardCharsets.UTF_8) == null) {
    throw new IllegalStateException("advisor jar resources missing — re-check packaging");
}

try {
    advisor = ToolSearchToolCallingAdvisor.builder().build();
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("classpath resource")) {
        // repackage or reinstall the spring-ai-tool-search-advisor jar
    }
    throw e;
}

When it happens

Trigger: Calling ToolSearchToolCallingAdvisor.builder().build() (directly or via auto-configuration) when the resource DEFAULT_SYSTEM_PROMPT_SUFFIX.md is absent from the classpath or unreadable.

Common situations: ProGuard/shade plugins stripping resources, fat-jar repackaging that drops .md files, dependency exclusions removing resource files, or running from an exploded classpath where resources were not copied to target/classes.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• SSE connection '<connectionName>' requires a 'url' property.
• Found 2 elicitation handlers for client [%s], found in bean
• Found 2 sampling handlers for client [%s], found in bean wit
• Microsoft Foundry was detected, but no credential was provid
• IOException (wrapped RuntimeException)

AI-assisted analysis of spring-projects/spring-ai@98a7beda4f (2026-09-11). Data as JSON: /api/errors/46f6dddb1718cad6. Report an issue: GitHub.