Debugging INSUFFICIENT_ACCESS_OR_READONLY in Apex

We recently ran into this Salesforce error during an update operation:

Update failed. First exception on row 3 with id <recordId>; first error: INSUFFICIENT_ACCESS_OR_READONLY, insufficient access rights on object id: []

At first, the error did not clearly point to the root cause. To debug it, we added a small check before the update statement in our Apex queue class to verify whether the running user had edit access to the records being processed.

Set<Id> recordIds = new Map<Id, CustomObject__c>(recordsToUpdate).keySet();
Set<Id> recordsWithoutEditAccess = new Set<Id>();

for (UserRecordAccess access : [
    SELECT RecordId, HasEditAccess
    FROM UserRecordAccess
    WHERE UserId = :UserInfo.getUserId()
    AND RecordId IN :recordIds
]) {
    if (!access.HasEditAccess) {
        recordsWithoutEditAccess.add(access.RecordId);
    }
}

System.debug(
    LoggingLevel.WARN,
    'Running user: ' + UserInfo.getUserId()
        + '; records without edit access: ' + recordsWithoutEditAccess
);

This confirmed that the failure was caused by record-level access. The user context under which the queue was running did not have edit access to some of the records.

Based on that, we updated the class to run without sharing, which resolved the issue.

The main takeaway: when you see INSUFFICIENT_ACCESS_OR_READONLY in Apex, it is worth validating record access explicitly. A small UserRecordAccess check can quickly confirm whether the issue is with business logic or sharing context.