java.lang.ClassNotFoundException: com.example.MissingClass

What it means

Java resolves most classes when they are first needed rather than all at once at startup, and it resolves them by name against a classpath. Inside a Lambda execution environment that classpath is fixed: /var/task/, every jar under /var/task/lib/, and anything a layer places under /opt. Nothing from your build machine, your IDE's run configuration, or your local Maven repository is present.

ClassNotFoundException is thrown when something asked the classloader for a class by name and it was not found on that path. The "by name" part matters, and is the reason this error survives a successful compile: reflection, service loaders, dependency-injection frameworks and JSON deserializers all resolve classes from strings at runtime, so the compiler has nothing to check. Lambda itself does exactly this to load your handler, which is why a handler misconfiguration surfaces as a ClassNotFoundException naming your own class.

Because resolution is lazy, the timing of the failure is informative. A class needed to construct your handler fails during init, so every invocation dies the same way and none of your code runs. A class needed only on one branch — an error formatter, an optional integration — fails only when that branch is taken, which produces a deployment that appears healthy until a particular kind of request arrives. Reading the stack trace to see where the load was attempted separates those two immediately.

The distinction worth keeping straight is against its close relative, NoClassDefFoundError. ClassNotFoundException means the class was never found. A NoClassDefFoundError means it was found once, failed to initialise, and every subsequent attempt to use it fails too. They read almost identically in a log and point at completely different problems — one is a packaging fault, the other is usually an exception thrown in a static initialiser.

What it looks like in CloudWatch

This is the shape the failure arrives in: the lines of one invocation scattered among everything else the log group received at the same moment.

The panel on the right is generated by running the excerpt on the left through the same parser that powers the free web stitcher — it is what the tool actually produces for this input, not an illustration of it.

How to confirm it from the logs

Read the fully-qualified class name in the message and decide which of two cases you have. If it is your own handler class, Lambda could not load the entry point at all and the handler configuration or the artifact layout is wrong. If it is a third-party class — something under com.amazonaws, org.apache, com.fasterxml — a dependency did not make it into the jar.

The stack trace beneath tells you when it happened. A failure inside URLClassLoader.findClass during init means the class was needed to construct your handler. A failure deeper in your own call stack means it was needed lazily, part-way through a request — which is why some invocations can succeed while others fail on the same deployment.

Causes, most likely first

Fixes

xml<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-shade-plugin</artifactId>
  <version>3.5.1</version>
  <executions>
    <execution>
      <phase>package</phase>
      <goals><goal>shade</goal></goals>
    </execution>
  </executions>
</plugin>

bash# Is the class actually in there?
unzip -l target/function.jar | grep -i 'MissingClass'

# And what does the handler string need to match?
unzip -p target/function.jar META-INF/MANIFEST.MF

yamlResources:
  OrderFunction:
    Type: AWS::Serverless::Function
    Properties:
      # package.Class::method — the package prefix is required
      Handler: com.example.orders.OrderHandler::handleRequest
      Runtime: java21

bashmvn dependency:tree -Dverbose -Dincludes=com.fasterxml.jackson.core

Also seen as

The same underlying failure, worded differently by a different runtime, SDK version, or logging layer. All of these land here — there is no separate page for each phrasing.

Related errors

Errors that show up alongside this one, or that people mistake for it.

References

• AWS Lambda Developer Guide — Deploy Java Lambda functions with .zip or JAR file archives
• AWS Lambda Developer Guide — Define Lambda function handler in Java