How do I troubleshoot "ClassNotFoundException" errors with my Java Lambda function?

Last updated: 2020-02-28

When I run my AWS Lambda function written in Java, I get "ClassNotFoundException" or "NoSuchMethodError" errors. How do I fix these errors?

Short Description

The Java runtime raises "ClassNotFoundException" errors when it tries to load a class by its fully qualified name (the package with the class name) and fails to locate the class. The runtime raises "NoSuchMethodError" errors when a referenced dependency version is different from the packaged version.

For information about Java function deployment package structure, see Creating a ZIP Deployment Package for a Java Function.


Review the structure and contents of your Java Lambda function's deployment package to determine the cause of the error. As a best practice, use zipinfo to view the output Java file of your build system. Or, you can download the package by doing either of the following:

  • Run the Lambda get-function command from the AWS Command Line Interface (AWS CLI). The command output shows a presigned URL that you can use to download the file. For more information, see Retrieve a Lambda Function.
    Note: If you use this option, in the output also check the configuration for the value of your function handler. You need this value for the next step.
  • On the Functions page of the Lambda console, choose your function. Choose Actions, and then choose Export function. In the Export your function dialog box, choose Download deployment package.

Look for any of the following issues. After you identify and fix the issues, manually bundle and upload your Lambda function. Then, check to see if you still get the error.

Confirm the function handler method name

Check the name of your Lambda function handler by doing either of the following:

For more information, see AWS Lambda Function Handler in Java.

View the deployment package structure

Run the following command to view your Lambda function deployment package's file structure:

Note: This command is valid only for Linux/Unix/macOS systems. Replace with your deployment package's file name.

$ zipinfo

Check for issues when using a CI/CD pipeline

If you're using a continuous integration and continuous delivery (CI/CD) pipeline to package and deploy your function, verify the following:

  • All required dependencies were bundled when packaging the function.
  • All referenced dependency versions are correct.
  • If you use an Amazon Simple Storage Service (Amazon S3) bucket source and bucket versioning is enabled, the S3 bucket URL exists and points to the latest version of a file.
  • The code changes were deployed before deploying the handler configuration change. (Lambda doesn't have a mechanism for updating code and configuration in one atomic change.)

Check for class file issues

Verify the following for the class named in the "ClassNotFoundException" error:

  • It's included in the deployment package. If you can't find the class, it might not have been bundled when you created the deployment package.
  • Its bundled class name is the same as your function's handler value. For example, if your function handler value is com.amazonaws.lambda.demo.LambdaFunctionHandler", then Lambda expects a class name of "LambdaFunctionHandler.class" in the function directory "/com/amazonaws/demo/". For more information, see AWS Lambda Function Handler in Java.
  • It's located in /lib or the root directory.
  • Its location is specified in a Java CLASSPATH environment variable.
  • If it's referenced as a Lambda layer, its contents weren't extracted to a directory other than java/lib.
  • It's the same version as the class packaged with your function. If not, check if your local machine had a different version than what you packaged.

For more information about packaging Java functions, see AWS Lambda Deployment Package in Java.

Check for JAR file issues

Confirm if your function executes as expected on a local machine, or from an AWS Serverless Application Model (AWS SAM) application. If your function fails only when invoked from Lambda, there could be issues with referenced dependencies (JAR files).

Tip: Consider using the Eclipse integrated development environment (IDE) to build your Java Lambda functions. Creating a project using plugins available in Eclipse automatically configures your project for a proper build. For more information, see Using Lambda with the AWS Toolkit for Eclipse.

Verify the following for JAR files that are located in a local directory and specified in a Java CLASSPATH environment variable:

  • The files are included in your function's deployment package. If you can't find referenced JAR files, they might not have been bundled when you created the deployment package.
  • The file versions are the same as the files in the deployment package.

If files are missing or their versions are incorrect, copy all the dependencies (JAR files) to /lib or the root directory. Be sure to reference the correct versions. Then, upload the zipped contents.

Note: If you're using a build tool such as Apache Maven or Gradle, be sure to use any necessary plugins (for example, the Apache Maven Shade Plugin) to bundle all required dependencies when building the deployment artifact.

For more information about packaging Java functions, see AWS Lambda Deployment Package in Java.

Check for permissions issues

Lambda requires that zip package files have global read permissions. For more information, see How do I troubleshoot Lambda "permission denied" or "unable to import module" errors when uploading a deployment package?