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

Short description

The "ClassNotFoundException" error occurs when Java runtimes loads a class by its fully qualified name, but doesn't locate the class.

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 you run AWS Command Line Interface (AWS CLI) commands, then see Troubleshooting errors for the AWS CLI. Also, make sure that you're using the most recent AWS CLI version.

Download your Lambda function's deployment package

To download your Lambda function's deployment package, use either the AWS CLI or the AWS Management Console.

AWS CLI

Run the following get-function command:

aws lambda get-function \
    --function-name  your-function-name

Note: Replace your-function-name with your Lambda function.

The preceding command output provides a link to download the deployment package.

AWS Management Console

Complete the following steps:

1. Open the Lambda console.
2. In the navigation pane, choose Functions, and then select the Lambda function that you want to download the deployment package.
3. Choose the Download dropdown list, and then select Download function code zip.

Check for CI/CD pipeline issues

If you use a continuous integration and continuous delivery (CI/CD) pipeline to package and deploy your function, then check your configuration requirements.

Complete the following actions:

• Make sure that you bundle all required dependencies when packaging the function.
• Confirm that all referenced dependency versions are correct.
• Make sure that any required Amazon Simple Storage Service (Amazon S3) bucket URLs exist and points to the latest version of your JAR file.
  Note: The Amazon S3 bucket URL is required if you use an Amazon S3 bucket source and bucket versioning is activated.
• Make sure that you deployed coded changes before handler configuration deployments.
  Note: Lambda doesn't have a mechanism for updating code and configuration in one atomic operation.

Check for class file issues

For "ClassNotFoundException" errors, check the class name specified in the output for your configuration requirements.

Complete the following actions:

• Make sure that the class is 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.
• Make sure that the bundled class name is the same as your function's handler value. For more information, see Define Lambda function handler in Java.
• Confirm that the class exists in the /lib or root directory.
  Note: If the class is referenced as a Lambda layer, then its contents weren't extracted to a directory other than java/lib.
• Make sure that the class is the same version as the class packaged with your function. If the class isn't the same version, then check if your local machine has a different version than what you packaged.

Check for JAR file issues

Confirm that your function runs correctly 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.

Check the JAR files to confirm that they exist in a local directory and that the Java CLASSPATH environment variable specifies them. Make sure that you include the JAR files in your function's deployment package. Also, make sure that the JAR file versions are the same as the files in the deployment package.

Note: If you can't find any referenced JAR files, then you might not have bundled them when you created the deployment package.

If JAR files are missing or their versions are incorrect, then copy all the dependencies to the /lib or the root directory. Make sure that you reference the correct versions. Then, upload the zipped contents.

Note: If you use a build tool like Apache Maven or Gradle, then make sure that you use the required plugins when building the deployment artifact.

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

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

Related information

Instrumenting Java code in AWS Lambda

Best practices for working with AWS Lambda functions

How do I reduce initialization and invocation duration latency for my Java Lambda function?