Troubleshooting.

Start by running synchronization explicitly and inspecting all four result buckets:

$result = $source->syncMentions();

dump([
    'created' => count($result->created),
    'retained' => count($result->retained),
    'removed' => count($result->removed),
    'unresolved' => $result->unresolved,
]);

This separates parser and resolver misses from model-event problems.

The configured resolver throws

Mention resolver definitions require resolver, model, and column classes. means an array definition is missing a valid resolver class, Eloquent model class, or string column.

The resolver key is optional and defaults to ColumnMentionResolver. The model and column values are required for an array definition.

Mention resolver [...] must implement MentionResolver means the container returned the wrong object for the configured class.

A handle stays unresolved

Check these values in order:

1. The parser returned the expected handle without its trigger.
2. The resolver model points to the intended Eloquent class.
3. The resolver column stores the expected handle.
4. The target row exists before the source is synchronized.
5. An earlier resolver has not claimed a shared handle.

The default column resolver is case insensitive. % and _ remain literal handle characters rather than SQL wildcards.

Markup IDs do not resolve

Confirm data-mention-type matches a resolver key and that its definition has a model value. A class-string-only resolver cannot map markup IDs.

When you omit the type, the package uses the first array resolver containing a model. An unknown type and a missing target ID both remain unresolved.

Saving leaves stale mention rows

Normal Eloquent save() and update() calls trigger automatic sync. saveQuietly(), query-builder updates, bulk inserts, and raw SQL do not.

Call syncMentions() after a write that bypasses model events. Also confirm mentions.auto_sync is the boolean true and the model does not override syncsMentionsAutomatically() to return false.

The parser is not registered

The configured mention parser is not registered. means default_parser or a model's mentionParser() return value has no class-string entry in parsers.

Mention parser [...] must implement MentionParser means the configured class does not satisfy the contract.

The regex parser throws

Mention trigger and handle pattern must be non-empty strings. means trigger or handle_pattern is empty or has another type.

mentions.handle_pattern must be a valid regular-expression fragment. means the configured fragment cannot be compiled. Remove regex delimiters and test the fragment independently.

A deleted target still has mention rows

The target trait does not register a deleting listener. Deleting a target can leave rows whose target relation returns null.

Apply target cleanup in your application when retention does not require those rows:

protected static function booted(): void
{
    static::deleting(function (User $user): void {
        $user->mentionedIn()->delete();
    });
}

Decide separately how soft-deleted targets should behave.

A restored source has stale mentions

Soft delete preserves rows, and restore does not rescan text. Call syncMentions() after restore when the stored text changed while deleted.

A listener fails after the row changes

Lifecycle events run after the package transaction. In ordinary auto-commit use, a listener exception reaches the caller after the package writes the diff.

Make notification listeners retry-safe. Use an application-owned outer transaction only when source and mention persistence must share rollback behavior.

Get help

For usage questions, start a GitHub discussion. For a reproducible package defect, open a GitHub issue with a minimal test case.

What to read next

• Configuration to compare each current value with its accepted shape.
• Parsing text to inspect candidate boundaries.
• Control synchronization for model-event blind spots.