Introduction

The classpath is one of those Java concepts that feels invisible until something fails to load. In Spring Boot, understanding the classpath helps you explain why dependencies are discovered automatically, why application.properties is found without extra wiring, and why a packaged jar behaves differently from a plain Java project.

What the Classpath Means in Spring Boot

At the JVM level, the classpath is the set of directories and jar files used to locate classes and resources. Spring Boot builds on that mechanism. When your application starts, the JVM and Spring both search the classpath for:

• compiled application classes
• dependency jars
• configuration files
• templates and static assets

In a standard Maven or Gradle project, anything under src/main/java is compiled into classes, and anything under src/main/resources is copied onto the runtime classpath.

That is why a file like src/main/resources/application.properties is available automatically at startup.

Loading Classpath Resources

Spring provides several ways to read files from the classpath. The most explicit is ClassPathResource.

1import java.io.IOException;
2import java.nio.charset.StandardCharsets;
3
4import org.springframework.core.io.ClassPathResource;
5
6public class ResourceExample {
7    public static void main(String[] args) throws IOException {
8        ClassPathResource resource = new ClassPathResource("messages.txt");
9        String text = new String(resource.getInputStream().readAllBytes(), StandardCharsets.UTF_8);
10        System.out.println(text);
11    }
12}

For this to work, messages.txt should live in src/main/resources.

Spring also supports the classpath: prefix in places where a resource location is configured:

1import org.springframework.beans.factory.annotation.Value;
2import org.springframework.core.io.Resource;
3import org.springframework.stereotype.Component;
4
5@Component
6public class TemplateLoader {
7
8    @Value("classpath:templates/email-template.txt")
9    private Resource template;
10
11    public Resource getTemplate() {
12        return template;
13    }
14}

The classpath: prefix makes your intent explicit and avoids mixing file system paths with packaged resources.

How Dependencies Reach the Classpath

Dependencies declared in Maven or Gradle become part of the application classpath according to their scope or configuration.

A simple Maven example:

1<dependencies>
2    <dependency>
3        <groupId>org.springframework.boot</groupId>
4        <artifactId>spring-boot-starter-web</artifactId>
5    </dependency>
6
7    <dependency>
8        <groupId>com.fasterxml.jackson.core</groupId>
9        <artifactId>jackson-databind</artifactId>
10    </dependency>
11</dependencies>

A similar Gradle example:

1dependencies {
2    implementation 'org.springframework.boot:spring-boot-starter-web'
3    runtimeOnly 'com.h2database:h2'
4    testImplementation 'org.springframework.boot:spring-boot-starter-test'
5}

The important detail is that not every dependency is available in every phase. A testImplementation dependency is on the test classpath, not the main runtime classpath. That distinction explains many ClassNotFoundException problems.

Why Spring Boot Fat Jars Feel Different

A packaged Spring Boot jar is not laid out like a plain Java jar with all classes flat at the top level. Boot creates an executable archive that contains:

• your compiled classes
• your resource files
• dependency jars nested inside the archive

When you run java -jar app.jar, Spring Boot uses its launcher to assemble the effective runtime classpath from those nested jars. That is why a resource that works in your IDE usually still works inside the packaged artifact, as long as it was added to src/main/resources and not referenced through a hardcoded file path.

Common Resource Patterns

Two patterns appear in most Boot applications.

Reading a configuration or seed file:

1import java.io.BufferedReader;
2import java.io.IOException;
3import java.io.InputStreamReader;
4
5import org.springframework.core.io.ClassPathResource;
6
7public class SeedReader {
8    public static void main(String[] args) throws IOException {
9        ClassPathResource resource = new ClassPathResource("data/seed.txt");
10
11        try (BufferedReader reader =
12                 new BufferedReader(new InputStreamReader(resource.getInputStream()))) {
13            reader.lines().forEach(System.out::println);
14        }
15    }
16}

Referencing a SQL script in configuration:

spring.sql.init.schema-locations=classpath:db/schema.sql
spring.sql.init.data-locations=classpath:db/data.sql

Both examples rely on the resource being packaged on the classpath rather than existing as an external file beside the jar.

Common Pitfalls

The most common mistake is using a file system path for something that should be loaded from the classpath. Code that points to src/main/resources/... may work in the IDE and then fail once the application is packaged, because those source directories do not exist in production.

Another issue is placing files in the wrong source folder. If a resource is saved under src/test/resources, it will be available during tests but missing at runtime.

Dependency scopes also cause confusion. If a library is declared only for tests, your application compiles in the wrong environment and then fails at startup with missing classes.

Finally, developers sometimes assume Spring Boot scans every package automatically. Component scanning starts from the package of the main application class. That is related to classpath visibility but not the same thing. A class can be present on the classpath and still not be discovered as a Spring bean if it is outside the scan path.

Summary

• The classpath is the runtime search path for classes and resource files.
• In Spring Boot, src/main/resources is copied onto the application classpath.
• Use ClassPathResource or the classpath: prefix to load packaged resources.
• Dependency scope determines whether a library is available at runtime, test time, or both.
• Avoid hardcoded source-directory paths because packaged Spring Boot jars load resources differently.