What causes the “Unable to find Apex action class” error?

Question:

Why do I get the error “Unable to find Apex action class” when creating a new version of a 2nd generation package?

When working with 2nd Generation Salesforce Packages (2GP), developers often face challenges while creating new versions of packages or when adding new components to existing packages. One such issue you might encounter is the error message:

admin: Unable to find Apex action class referenced as 'AdminController'.

This error typically happens when you’re attempting to create a new version of a package that contains custom fields added via XML files, but despite all necessary components being in place, Salesforce is unable to find an Apex class that was referenced in the past. Let’s dive deeper into why this happens and how to resolve it.

Understanding the Issue

The error occurs during the process of creating a new version of a 2GP when Salesforce tries to deploy the components, such as Apex classes, from your source to a target org (like a scratch org). The specific error in question states that Salesforce can’t find the class AdminController, which is part of your previous version but seemingly not referenced by the new changes.

What’s perplexing is that the class exists in previous versions, and none of your new components (the new files you’ve added) reference or rely on this class. The question then arises: Why does Salesforce raise an error for a class that’s already in your previous versions, especially when the new files don’t interact with it?

Answer

Root Causes of the Error

Let’s break down the possible causes behind this error and the solutions to fix it.

1. Class Compilation Failure During Package Creation

One of the most common causes for this error is that the AdminController class fails to compile when Salesforce tries to package your changes.

When Salesforce creates a 2GP, it essentially goes through a deployment-like process. This process involves compiling all your code and verifying dependencies before creating a new version of the package. If any class fails to compile—even if it’s not directly related to the new files—Salesforce will fail the deployment and display the error.

Solution:

To identify this issue, deploy the source code to a new scratch org to verify if the AdminController class compiles correctly. If the class doesn’t compile, Salesforce might throw the error, thinking the class isn’t available.

You can run a deployment command like this to test the compilation:

sfdx force:source:deploy -p force-app/main/default/classes/AdminController.cls -u my-scratch-org

If you encounter any errors, investigate the class code, check for syntax issues, missing dependencies, or logic errors, and fix them. Once the class compiles successfully, you should be able to proceed with packaging your changes.

2. Deployment-Specific Errors in the Packaging Process

Salesforce 2GP packages undergo a deployment-like process during creation, which can result in hidden errors related to class references or metadata. Even though the AdminController class is not being modified, errors during the packaging process might cause Salesforce to fail the deployment because the class cannot be found.

This is a bit tricky because the error may not necessarily lie in the code you’re editing; it might be due to deployment configuration issues or missing references in the package metadata.

Solution:

To troubleshoot this, check all the dependencies and ensure your class is properly included in the package’s metadata. Additionally, validate the deployment logs to see if any classes or components failed during the packaging process. In some cases, Salesforce will provide more detailed logs that can guide you to the specific issue.

3. Apex Class Dependencies and Visibility Issues

Even though the AdminController class appears to exist in your previous package versions, there could be dependency or visibility issues preventing it from being recognized during the package creation process. For example, if the class relies on other components that were modified or removed in the new version, it may cause Salesforce to fail in identifying the class properly.

Solution:

If you recently modified any dependencies of the AdminController class, review the changes closely. Ensure that no visibility or access issues are affecting the class. If necessary, deploy related classes first before proceeding with the package creation to ensure all dependencies are correctly packaged.

If AdminController relies on another class, say HelperClass, you can deploy them separately to check for errors:

sfdx force:source:deploy -p force-app/main/default/classes/HelperClass.cls -u my-scratch-org

Once you’ve resolved any dependency issues and ensured all related classes are deployed, try packaging the new version again.

Additional Considerations

4. Check for Deleted Classes or Metadata

If the AdminController class was deleted or removed in any previous deployments or versions, Salesforce might throw this error when it can’t find the class in the current environment. In such cases, removing the class from the package may not be ideal since it could break the functionality for other parts of the package.

If deletion of the class was unintentional, restore the class from the backup or version control and deploy it again. Be cautious about removing classes that are still referenced in your org, as it may affect existing deployments or functionality.

5. Check for Salesforce Metadata Cache Issues

Sometimes, metadata cache issues in Salesforce may prevent proper recognition of existing classes. If everything seems fine, and your classes should compile and be available, consider clearing any metadata caches or refreshing your scratch org environment.

sfdx force:org:delete -u my-scratch-org
sfdx force:org:create -s -f config/project-scratch-def.json

This approach ensures that your scratch org is clean and up to date with the latest metadata.

Conclusion

When encountering the “Unable to find Apex action class referenced as ‘AdminController’” error during 2GP version creation, start by checking the class’s compilation status. Salesforce treats the packaging process like a deployment, so confirming the class compiles correctly and dependencies are intact is essential. Additionally, investigate potential deployment issues, class visibility, and metadata cache problems to resolve the error.

2GP packaging requires careful management of class references and dependencies. Thorough testing in scratch orgs is crucial for smooth deployment and ensuring all components are properly packaged and deployed.

Salesforce Training in Chennai – Boost Your Career Today!

The Salesforce training also includes personalized mentorship, interview coaching, and exam preparation, ensuring you’re ready to stand out in the job market. Through hands-on projects, comprehensive study materials, and continuous support, you’ll gain the confidence to earn top certifications and demonstrate your practical skills to employers. Start your Salesforce journey now and unlock new career opportunities!

Our Salesforce Training in Chennai offers an in-depth, hands-on learning experience, equipping you with the skills needed to excel in the CRM industry. Covering Salesforce Admin, Developer, and AI domains, the program blends theoretical knowledge with practical applications, tackling real-world business challenges. With expert instructors and industry-relevant projects, you’ll enhance your technical expertise and gain a deep understanding of the CRM ecosystem.

Take the first step towards a successful Salesforce career—register for a FREE demo session today..!