{"id":"fd9dc77887e54dc9","repo":"laravel/framework","slug":"the-provided-value-may-not-be-null","errorCode":null,"errorMessage":"The provided value may not be null.","messagePattern":"The provided value may not be null\\.","errorType":"exception","errorClass":"InvalidArgumentException","httpStatus":null,"severity":"error","filePath":"src/Illuminate/Database/Eloquent/Relations/BelongsToMany.php","lineNumber":493,"sourceCode":"     *\n     * @param  string|\\Illuminate\\Contracts\\Database\\Query\\Expression|array<string, string>  $column\n     * @param  mixed  $value\n     * @return $this\n     *\n     * @throws \\InvalidArgumentException\n     */\n    public function withPivotValue($column, $value = null)\n    {\n        if (is_array($column)) {\n            foreach ($column as $name => $value) {\n                $this->withPivotValue($name, $value);\n            }\n\n            return $this;\n        }\n\n        if (is_null($value)) {\n            throw new InvalidArgumentException('The provided value may not be null.');\n        }\n\n        $this->pivotValues[] = ['column' => $column, 'value' => $value];\n\n        return $this->wherePivot($column, '=', $value);\n    }\n\n    /**\n     * Set an \"or where in\" clause for a pivot table column.\n     *\n     * @param  string  $column\n     * @param  mixed  $values\n     * @return $this\n     */\n    public function orWherePivotIn($column, $values)\n    {\n        return $this->wherePivotIn($column, $values, 'or');\n    }","sourceCodeStart":475,"sourceCodeEnd":511,"githubUrl":"https://github.com/laravel/framework/blob/bd6b5437e6ad87bb49f9b426724f07a9f64e9683/src/Illuminate/Database/Eloquent/Relations/BelongsToMany.php#L475-L511","documentation":"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.","triggerScenarios":"Calling $model->relation()->withPivotValue('column', null) or passing an array ['col' => null] that recurses into the scalar form with null.","commonSituations":"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.","solutions":["Only call withPivotValue when you have a concrete non-null value; skip the call when value is null.","Use wherePivotNull('column') if you genuinely want rows where the pivot column is null.","Filter nulls out of array input before passing to withPivotValue(['a' => 1, 'b' => 2])."],"exampleFix":"// before\n$query = $user->roles()->withPivotValue('team_id', $request->team_id); // null if missing\n\n// after\n$query = $user->roles();\nif ($request->filled('team_id')) {\n    $query->withPivotValue('team_id', $request->team_id);\n}","handlingStrategy":"validation","validationCode":"$query = $relation();\nforeach (array_filter($pivotFilters, fn ($v) => ! is_null($v)) as $col => $val) {\n    $query->withPivotValue($col, $val);\n}","typeGuard":"function isNonNullPivotValue(mixed $value): bool {\n    return ! is_null($value);\n}","tryCatchPattern":"try {\n    $relation->withPivotValue($column, $value);\n} catch (\\InvalidArgumentException $e) {\n    if (str_contains($e->getMessage(), 'may not be null')) {\n        // skip or use wherePivotNull if null-match intended\n    }\n    throw $e;\n}","preventionTips":["Filter null values out of pivot input before withPivotValue.","Use wherePivotNull when you genuinely need null-match.","Gate the call behind a filled()/!is_null() check for request input."],"tags":["eloquent","relationships","belongs-to-many","pivot","validation"],"analyzedSha":"bd6b5437e6ad87bb49f9b426724f07a9f64e9683","analyzedAt":"2026-08-06T00:28:32.783Z","schemaVersion":2}