How do I troubleshoot "ClassNotFoundException" and "NoSuchMethodError" errors from a Java Lambda function?

Last updated: 2022-02-03

When I try to invoke my Java AWS Lambda function, I get "ClassNotFoundException" or "NoSuchMethodError" errors. How do I resolve 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: A fully qualified class name in Java includes a class's 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 Lambda function deployment package structure, see Deploy Java Lambda functions with .zip or JAR file archives.

Resolution

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.

Download your Lambda function's deployment package

To view your Lambda function's deployment package's file structure, do one of the following:

To download your function's deployment package by running the zipinfo command

Run the following zipinfo command:

Important: Replace my-deployment-package.zip with your deployment package's file name. The following command is valid for Linux, Unix, and macOS operating systems only.

$ zipinfo my-deployment-package.zip

To download your function's deployment package by running the Lambda get-function AWS CLI command

Run the following get-function command:

Important: Replace my-function with your Lambda function's name.

aws lambda get-function \
    --function-name  my-function

The command output provides a presigned URL that you can use to download the file. For more information, see Retrieve a Lambda function.

To download your function's deployment package from the Lambda console

1.    On the Functions page of the Lambda console, choose your function.

2.    Choose Actions.

3.    Choose Export function.

4.    In the Export your function dialog box, choose Download deployment package.

Confirm the function handler method name

For more information, see AWS Lambda function handler in Java.

Check for any CI/CD pipeline issues

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 if you use an Amazon S3 bucket source and bucket versioning is activated only.
  • 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 any class file issues

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

  • It's included in the deployment package.
    Note: If you can't find the class, then 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.
  • It's located in the /lib or the root directory.
  • 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 the class isn't the same version, check if your local machine had a different version than what you packaged.

Check for any 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, then there might 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.
    Note: 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 the /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 like Apache Maven or Gradle, make sure that you use the required plugins when building the deployment artifact. For example, the Apache Maven Shade Plugin.

Check for any 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 Lambda deployment package?

Important: After you identify and fix the issues, you must manually bundle and upload your Lambda function to deploy it. Then, check to see if you still get the error.