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

Last updated: 2021-01-07

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 “ClassNotFoundException” error occurs when a Java runtime loads a class by its fully qualified name, but doesn’t locate the class.

Note: The fully qualified name for a class includes its deployment package and class name.

The "NoSuchMethodError" error occurs when a referenced dependency version is different from the packaged version.

For more information about Java function deployment package structure, see Creating a ZIP deployment package for a Java function.


Note: If you receive errors when running AWS Command Line Interface (AWS CLI) commands, make sure that you’re using the most recent AWS CLI version.

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 one of the following:

  • Run the Lambda get-function command from the 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, also check the configuration for the value of your function handler in the output. You need this value for the next step.
  • On the Functions page of the Lambda console, choose your function, then do the following:
    Choose Actions.
    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 one 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: The following command is valid only for Linux/Unix/macOS systems. Make sure that you 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.
  • Any required Amazon Simple Storage Service (Amazon S3) bucket URL exists and points to the latest version of a file.
    Note: The Amazon S3 bucket URL is required only if you use an Amazon S3 bucket source and bucket versioning is enabled.
  • The code changes were deployed before the handler configuration change was deployed.
    Note: 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 runs 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. Make sure that you reference the correct versions. Then, upload the zipped contents.

Note: If you’re using a build tool such as Apache Maven or Gradle, make sure that you use the required plugins when building the deployment artifact. For example, the Apache Maven Shade Plugin.

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?