{"record":{"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/e0f6eb3518ac29fbbca8529e97d0df7fc9f24481/src/Illuminate/Database/Eloquent/Relations/BelongsToMany.php#L475-L511","documentation":"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).","triggerScenarios":"Calling $relation->withPivotValue('approved', null), or passing an array with a null value: ->withPivotValue(['approved' => null]).","commonSituations":"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.","solutions":["Provide a concrete value: withPivotValue('approved', false) or withPivotValue('approved', 0).","If you actually need to match NULL pivot rows, use wherePivotNull('approved').","Guard the input: only call withPivotValue when the value is non-null."],"exampleFix":"// before\n$tags = $post->tags()->withPivotValue('approved', $request->input('approved'))->get();\n// throws when input('approved') is null\n\n// after\n$value = $request->input('approved');\n$query = $post->tags();\nif ($value === null) {\n    $query->wherePivotNull('approved');\n} else {\n    $query->withPivotValue('approved', $value);\n}\n$tags = $query->get();","handlingStrategy":"validation","validationCode":"// Never pass null; branch on intent\nif ($value === null) {\n    if ($wantNull) {\n        $query->wherePivotNull($column);\n    } else {\n        // skip the filter entirely\n    }\n} else {\n    $query->withPivotValue($column, $value);\n}","typeGuard":"function isNonNullPivotValue(mixed $value): bool {\n    return $value !== null;\n}","tryCatchPattern":"try {\n    $relation->withPivotValue($column, $value);\n} catch (\\InvalidArgumentException $e) {\n    if (str_contains($e->getMessage(), 'may not be null')) {\n        $relation->wherePivotNull($column); // if null matching was intended\n    } else { throw $e; }\n}","preventionTips":["Default request inputs to a real value (false, 0, ''), not null, before withPivotValue.","Use wherePivotNull when you specifically need to match NULL pivot rows.","Guard: skip the call entirely when the value is null and null-matching is not intended."],"tags":["eloquent","relationships","belongs-to-many","pivot","validation"],"backgroundTag":null,"analyzedSha":"e0f6eb3518ac29fbbca8529e97d0df7fc9f24481","analyzedAt":"2026-08-11T20:52:37.562Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}