laravel/framework · error · InvalidArgumentException

The provided value may not be null.

Error message

The provided value may not be null.

What it means

BelongsToMany::withPivotValue($column, $value) constrains the relation by a pivot column equal to a non-null value. The guard rejects a null value because filtering a pivot column 'where = null' is semantically different and almost always a caller bug (use wherePivotNull for that). It throws InvalidArgumentException before adding the clause.

Source

Thrown at src/Illuminate/Database/Eloquent/Relations/BelongsToMany.php:493

     *
     * @param  string|\Illuminate\Contracts\Database\Query\Expression|array<string, string>  $column
     * @param  mixed  $value
     * @return $this
     *
     * @throws \InvalidArgumentException
     */
    public function withPivotValue($column, $value = null)
    {
        if (is_array($column)) {
            foreach ($column as $name => $value) {
                $this->withPivotValue($name, $value);
            }

            return $this;
        }

        if (is_null($value)) {
            throw new InvalidArgumentException('The provided value may not be null.');
        }

        $this->pivotValues[] = ['column' => $column, 'value' => $value];

        return $this->wherePivot($column, '=', $value);
    }

    /**
     * Set an "or where in" clause for a pivot table column.
     *
     * @param  string  $column
     * @param  mixed  $values
     * @return $this
     */
    public function orWherePivotIn($column, $values)
    {
        return $this->wherePivotIn($column, $values, 'or');
    }

View on GitHub (pinned to bd6b5437e6)

Solutions

1. Only call withPivotValue when you have a concrete non-null value; skip the call when value is null.
2. Use wherePivotNull('column') if you genuinely want rows where the pivot column is null.
3. Filter nulls out of array input before passing to withPivotValue(['a' => 1, 'b' => 2]).

Example fix

// before
$query = $user->roles()->withPivotValue('team_id', $request->team_id); // null if missing

// after
$query = $user->roles();
if ($request->filled('team_id')) {
    $query->withPivotValue('team_id', $request->team_id);
}

$query = $relation();
foreach (array_filter($pivotFilters, fn ($v) => ! is_null($v)) as $col => $val) {
    $query->withPivotValue($col, $val);
}

function isNonNullPivotValue(mixed $value): bool {
    return ! is_null($value);
}

try {
    $relation->withPivotValue($column, $value);
} catch (\InvalidArgumentException $e) {
    if (str_contains($e->getMessage(), 'may not be null')) {
        // skip or use wherePivotNull if null-match intended
    }
    throw $e;
}

When it happens

Trigger: Calling $model->relation()->withPivotValue('column', null) or passing an array ['col' => null] that recurses into the scalar form with null.

Common situations: Building pivot filters from request input that may be unset/null; defaulting a missing pivot value to null; conditionally passing null when no filter applies.

Related errors

• Collection given to whereAttachedTo method may not be empty.
• Collection given to whereBelongsTo method may not be empty.
• The --model and --except options cannot be combined.
• Unsupported binary codec format [%s]. Allowed formats are: %
• Unable to create query for empty collection.

AI-assisted analysis of laravel/framework@bd6b5437e6 (2026-08-06). Data as JSON: /data/errors/fd9dc77887e54dc9.json. Report an issue: GitHub.