---
url: https://trigger.beyondthecloud.dev/before-insert/validator.md
description: >-
  Reject records before insert with a record-level or field-level error message,
  like a validation rule written in Apex.
---

# BeforeInsert.Validator

Reject new records before they are saved, like a validation rule written in Apex.

**Signature**

```apex
public interface Validator extends BeforeInsert.Handler {
    Boolean addErrorOnBeforeInsertWhen(TriggerTypes.InsertRecord record);
    void addErrorOnBeforeInsert(TriggerTypes.RejectableInsertRecord record);
}
```

* `addErrorOnBeforeInsertWhen(record)`: called once per record in the chunk. Return `true` to reject the record.
* `addErrorOnBeforeInsert(record)`: called right after its predicate returns true; it must attach an error to the record, or the library throws.

**Example**

::: code-group

```apex [Skeleton]
public with sharing class ContactValidator implements BeforeInsert.Validator {
    public Boolean addErrorOnBeforeInsertWhen(TriggerTypes.InsertRecord record) {
        return record.isBlank(Contact.Email);
    }

    public void addErrorOnBeforeInsert(TriggerTypes.RejectableInsertRecord record) {
        record.addError(Contact.Email, 'Email is required.');
    }
}
```

```cls \[Field error]
public with sharing class OpportunityAmountValidator implements BeforeInsert.Validator {
    public Boolean addErrorOnBeforeInsertWhen(TriggerTypes.InsertRecord record) {
        return record.isNotNull(Opportunity.Amount) && record.lessThanOrEqualTo(Opportunity.Amount, 0);
    }

    public void addErrorOnBeforeInsert(TriggerTypes.RejectableInsertRecord record) {
        record.addError(Opportunity.Amount, 'Amount must be greater than zero. Leave it empty until the deal value is known.');
    }
}

```

```cls \[Two messages]
public with sharing class ContactEmailFormatValidator implements BeforeInsert.Validator {
    public Boolean addErrorOnBeforeInsertWhen(TriggerTypes.InsertRecord record) {
        if (record.isBlank(Contact.Email)) {
            return false;
        }

        return record.doesNotContain(Contact.Email, '@') || this.isSharedMailbox(record);
    }

    public void addErrorOnBeforeInsert(TriggerTypes.RejectableInsertRecord record) {
        if (record.doesNotContain(Contact.Email, '@')) {
            record.addError(Contact.Email, 'Email must be a full address, for example jane.doe@example.com.');
            return;
        }

        record.addError(Contact.Email, 'A shared mailbox cannot be used as a contact email. Use the person\'s own address.');
    }

    private Boolean isSharedMailbox(TriggerTypes.InsertRecord record) {
        for (String prefix : new List<String>{ 'info@', 'sales@', 'support@', 'contact@', 'admin@', 'noreply@', 'no-reply@' }) {
            if (record.startsWith(Contact.Email, prefix)) {
                return true;
            }
        }

        return false;
    }
}

```

:::

## Rules {#rules}

* **Field errors add up.** `addError` does not stop the run. Later handlers still run for the record, and each Validator that rejects it on a field adds its own message. A second record-level error replaces the first, so the library sees no new error and throws.
* **Name and address fields lose the field.** On `Name` or a compound address field such as `BillingCity`, `record.addError(field, message)` shows the message at record level. Use `((Account) record.getNewSObject()).Name.addError(message)` instead.
* **Populator wins.** A class that also implements `BeforeInsert.Populator` runs only as a Populator. List Validators after the Populators, so they check the final values.
* **No DML.** If the handler runs DML or publishes an event, the library throws.

::: warning
Every qualified record must get an error. If one gets none, the whole chunk fails, even with [ContinueOnError](/before-insert/add-ons/continue-on-error).
:::

## Test {#test}

```apex
@IsTest
static void addErrorOnBeforeInsertWithNegativeAmount() {
    // Setup
    Opportunity renewal = new Opportunity(Amount = -100);

    TriggerOrchestrator.mock().beforeInsertFor(OpportunityAmountValidator.class).with(renewal);

    // Test
    TriggerOrchestrator.runTestFor(new OpportunityAmountValidator());

    // Verify
    Assert.areEqual(new List<String>{ 'Amount' }, renewal.getErrors()[0].getFields(), 'The error should be attached to Amount.');
}
```
