Common Salesforce Apex error messages and how to fix them

Even for experienced admins and developers, Apex errors can be difficult to unpick. The messages tend to be vague and give little indication as to their cause or a suitable fix. To save you time on Stack Exchange or Trailhead forums the next time you run into an Apex error message, we’ve compiled the best practices for handling Apex error messages and how to fix the most common ones!

Why are Apex code error messages so difficult to handle?

Apex is difficult even for those with experience with Java and C# because of some pesky quirks in the language. However, Apex error messages are particularly confusing because they are caught by exceptions that don’t always give you a clear reason for the problem.

What are Apex exceptions?

Exceptions, or ‘exceptional events’, are points in the execution of your Apex program that disrupts the normal flow of the transaction. Salesforce will ‘throw an exception’ when it catches a disruption in the running of your Apex, and will then display an error message.

There are two different types of exceptions:

Apex built-in exceptions, which are created by Salesforce to flag up common Apex errors. They will return an error message, but this is often vague.
Custom exceptions, which can be entirely new or an extension of the pre-built exceptions provided by Salesforce.

Admins and developers may create new custom exceptions to improve coding for integrations or to help guide end users through a workflow.
Predominantly, custom exceptions are an extension of the built-in exceptions. This is a best practice that’s done to provide more meaningful and specific error messages, which will help you to debug any Apex errors.

Both built-in and custom exceptions use the same methods, and return both the error message and exception type. You can access the full list of built-in Apex exceptions here, but be aware that different Salesforce orgs may have their own custom exceptions that you may come across.

How do you discover an error in your code?

Generally, you will be notified of any error by an end-user. They may either discover that their interface is not reflecting an update that was released, or they may be facing an error message on their own Salesforce interface. You’ll need to then work out what type of error has occurred, including one in your Apex code.

By default, unhandled Apex Apex exceptions will send an email to the last person to modify this component (i.e. named in the LastModifiedBy field). You can also customize who receives these notifications by following Salesforce’s developer guide. This email alert will give you two critical pieces of information:

Which user in which organization is experiencing this error. You can find this information from this section of the email:

Apex script [type of error] by user/organization: [User ID/Organization ID]

For example, Apex script [unhandled trigger exception] by user/organization: [1234/5678]

This information will allow you to replicate the issue that the user is experiencing.

The error message itself, which will be formatted as:

[Type of error]: [The error message]

For example, if you exceed the SOQL Queries Governors Limit, then you’ll get this message: TaskTrigger: System.LimitException: Too many SOQL queries: 101

The most common Apex errors in Salesforce, and how to fix them

Apex error messages are often vague, but there are a few common ones that you can learn which will help you with day-to-day debugging.

First Error: Insufficient Privileges

An ‘Insufficient Privileges’ error isn’t exclusive to Apex, and is indicating that you don’t have the right permission or sharing setting to either access a record or perform a task. It can be difficult to unpick when it’s prompted by an Apex run because it can mean either:

Your Apex job is accessing an object or field that you don’t have access to, or
You don’t have the permissions to perform a DML operation

You can resolve this by checking that you, or the user experiencing the issue, have the permissions required to perform these actions.

System.NullPointerException

This error message occurs because you’re referencing a null object, either because your query hasn’t returned an object, a variable hasn’t been initialized properly, or a field value has not been populated. You’ll need to dig into your Apex code to identify what’s causing issues by being set to null, and resolve this either:

In Apex, by checking that your code isn’t setting the object or variable to null before it’s accessed, or
By checking for null values in data records and related objects or variables.

You can also avoid this error message in future by creating defensive code to check if an object or variable is null before Apex accesses it or you could make it a required field so that your end users cannot leave it empty.

System.LimitException: Too many concurrent Apex requests

The cause of this error message is simple: you have too many Apex requests running in your org at the same time (the maximum for a single org is 10,000).

However, the solution is complex because it’ll require you to change your workflow. You can try to optimize your Apex code, also known as refactoring, to remove any inefficient operations while still keeping its behavior the same. If you don’t want to make any code changes, you’ll need to run your batch jobs asynchronously, but this can be eased by scheduling Apex job runs.

How should I approach Apex error messages?

Even with a good grip on the most common Apex error messages, you’ll likely run into a few that are a little tricker to unpick — both because the error message is vague and because the process of debugging is complex.

Identify the cause using the error message

Many built-in exceptions do come with suggestions for fixing the issue, which certainly speeds up the process. But even when built-in exceptions give vague error messages there are still a few useful pieces of information that you should be able to gain from them:

The general area of the problem should be made clear by either the error type or error message. This may help you narrow down the search when debugging.
The line of Apex code in which the error occurred should also be given. You can use this to find the object or variable that’s throwing the exception.

How to debug Apex code

Once you’ve identified an error and viewed the error message, it’s time to dig into resolving the exception. There are three avenues that will help you to debug Apex code that’s throwing an exception:

Checkpoints, which allow you to mark a location in your code that you wish to inspect. You can insert a System.debug() statement at this point in your code to print out the value of variables, which will help you unpick where the error occurred.
View state allows you to view the data and components of a page during its request and response cycle,
Logs provide the most comprehensive view of Apex execution, recording database operations, system processes and any errors. You can easily find the Salesforce debug log, for yourself or any other user, by setting a Trace Flag and then finding the log using either the Developer Console or the Setup menu.

These methods can all be used separately, but it’s generally best practice to use them in conjunction when you’re faced with an Apex error message.

Master Salesforce development

Apex error messages are difficult from a technical perspective, but they often indicate that something could improve in your workflow. If you want to learn how to implement Salesforce best practices so that you can develop more efficiently and effectively, check out our free courses on DevOps Launchpad and upskill for free!