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() filters the relationship to rows whose pivot column equals a given value. A null value is explicitly rejected because the method both stores the value for sync operations and applies wherePivot($column, '=', null) which would not behave as intended. Pass a concrete non-null scalar (or use wherePivotNull if you want null matching).

Solutions

1. Provide a concrete value: withPivotValue('approved', false) or withPivotValue('approved', 0).
2. If you actually need to match NULL pivot rows, use wherePivotNull('approved').
3. Guard the input: only call withPivotValue when the value is non-null.

Example fix

// before
$tags = $post->tags()->withPivotValue('approved', $request->input('approved'))->get();
// throws when input('approved') is null

// after
$value = $request->input('approved');
$query = $post->tags();
if ($value === null) {
    $query->wherePivotNull('approved');
} else {
    $query->withPivotValue('approved', $value);
}
$tags = $query->get();

// Never pass null; branch on intent
if ($value === null) {
    if ($wantNull) {
        $query->wherePivotNull($column);
    } else {
        // skip the filter entirely
    }
} else {
    $query->withPivotValue($column, $value);
}

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

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

When it happens

Trigger: Calling $relation->withPivotValue('approved', null), or passing an array with a null value: ->withPivotValue(['approved' => null]).

Common situations: Optional request input that defaults to null and is passed straight to withPivotValue; boolean flag that resolved to null; seeding a default that is null.

Related errors

• Collection given to whereAttachedTo method may not be empty.
• Collection given to whereBelongsTo method may not be empty.
• Invalid aggregate [ ] used within ofMany relation…
• Add fillable property
• Call to undefined method

AI-assisted analysis of laravel/framework@e0f6eb3518 (2026-08-11). Data as JSON: /api/errors/fd9dc77887e54dc9. Report an issue: GitHub.

Appendix: 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 e0f6eb3518)