Errors#

ACF Chef has four package exceptions.

Every one implements:

AcfChef\Exceptions\AcfChefException

so you can catch definition errors as a group:

use AcfChef\Exceptions\AcfChefException;

try {
    $group->toArray();
} catch (AcfChefException $exception) {
    // Handle an ACF Chef definition error.
}

Each exception also extends an appropriate SPL exception.

UnknownFieldType#

Raised when a verb has no registered field class.

For a near miss within edit distance two, ACF Chef suggests up to three likely verbs.

Otherwise the message points towards Chef::register() for a custom type.

See Fields and verbs for built-in verbs and Registering field types for extending the registry.

UnresolvedPath#

Raised when find(), modify() or remove() receives a path that does not address a field.

The message identifies where resolution stopped and, where possible, what fields were available there.

See Finding and editing fields for path syntax and failure diagnostics.

UnresolvedReference#

Raised when conditional logic refers to a field that cannot be resolved from the node tree.

This happens at compile time and covers the short conditional API, grouped conditions and raw conditional_logic arrays.

See Conditional logic for target resolution.

DuplicateFieldKey#

Raised when two fields in one group produce the same key in ACF Chef’s generated key map.

The exception includes the key and the node path that collided.

See Field keys for key generation and duplicate detection.

Not every failure is an AcfChefException#

Some errors deliberately remain ordinary SPL exceptions.

Catching only AcfChefException will not catch these.

Plain BadMethodCallException#

A plain BadMethodCallException is used when the failure is a method call or an unsupported operation rather than an invalid field definition.

Examples include:

• Calling an unknown method on a non-delegating cursor.
• Calling a method that does not exist on the extended-acf field inside deferred config().
• Calling add() or use() on a cursor whose field is not a container.
• Applying collapsed to a field type that does not support it.
• Applying conditional logic to a field type that does not support it.
• Calling an unknown cursor macro.
• Compiling a field class registered as a container when it has neither fields() nor layouts().

See Nesting and chaining, Configuring fields, Macros and shorthands and Registering field types for the corresponding APIs.

Plain InvalidArgumentException#

Bad arguments use ordinary InvalidArgumentException.

That includes:

• The four Chef::register() validation failures.
• Passing a closure or Recipe to a leaf field verb.
• Calling a field verb without a name.
• Passing a malformed raw conditional_logic array.
• Supplying a conditional rule without a valid target.
• Using an unsupported conditional operator.

See Registering field types, Fields and verbs and Conditional logic for the validation rules.

Choose the catch boundary you need#

Catch AcfChefException when you want to handle ACF Chef’s four definition errors as one category:

try {
    $array = $group->toArray();
} catch (AcfChefException $exception) {
    // Definition could not be compiled.
}

Catch the relevant SPL exception as well when your code also needs to handle invalid method calls or arguments:

try {
    $array = $group->toArray();
} catch (AcfChefException $exception) {
    // Package definition error.
} catch (BadMethodCallException | InvalidArgumentException $exception) {
    // Unsupported operation or invalid argument.
}

The distinction is intentional: AcfChefException identifies ACF Chef’s own definition-level failures, while ordinary PHP usage errors retain their standard SPL types.