PHP says a null argument is not allowed for a typed parameter
Deprecated: Passing null to parameter #2 ($needle) of type string is deprecatedShort answer
PHP treats null as a value of its own type. A parameter typed string or int does not accept it unless the type says so. In your own functions this is a TypeError; for built-in functions PHP 8.1 and later raise a deprecation. Fix it by marking the type nullable with ?T or T|null, or by passing a real value.
Fix it fast
1Find out which cause you have
Read the message and the file and line it names. A TypeError names your own function; a Deprecated notice that names a built-in function (str_contains, strlen, trim and so on) points to a built-in call that received null.
php -v && php -l path/to/file.php2Match what you see, then jump to its fix
- 1
Uncaught TypeError: ... Argument #1 ($c) must be of type CYour own function declares a non-nullable typeFix - 2
Deprecated: Passing null to parameter #2 ($needle) of type string is deprecatedA built-in function received null (PHP 8.1 and later)Fix - 3
A Deprecated notice about a parameter written as Type $x = nullA typed parameter is made nullable only by a null default (PHP 8.4 deprecates this)Fix
- 1
What does the error look like?
Deprecated: Passing null to parameter #2 ($needle) of type string is deprecatedUncaught TypeError: f(): Argument #1 ($c) must be of type C
Cause 1 of 3
Your own function declares a non-nullable type
1Check
Find the function signature and the call that passes null. A parameter typed C or string accepts only that type unless null is allowed explicitly.
grep -rn "function f(" src/2Fix
If null is a valid input, make the type nullable. ?C and C|null mean the same thing; ?T works since PHP 7.1 and T|null since PHP 8.0. If null is not valid, find where the value goes missing and fix the caller.
function f(?C $c)
{
if ($c === null) {
return;
}
}3Verify
Call the function with null and with a real object. Neither call should raise a TypeError.
php -r 'require "src/f.php"; f(null); f(new C); echo "ok\n";'Confirmed by php.net
Cause 2 of 3
A built-in function received null (PHP 8.1 and later)
1Check
Before 8.1, built-in functions accepted null for scalar parameters. Since 8.1 this is deprecated, so old code that passes an unset variable or a missing array key now logs a notice. The line number points at the call.
php -d error_reporting=E_ALL -d display_errors=1 index.php2Fix
Give the function a real value of the expected type. Use a default when null is expected, and do not cast blindly if a missing value should be treated as an error.
$needle = $maybeNull ?? '';
var_dump(str_contains("foobar", $needle));3Verify
Run the same script again. The Deprecated line for that call should be gone.
php -d error_reporting=E_ALL -d display_errors=1 index.phpConfirmed by php.net
Cause 3 of 3
A typed parameter is made nullable only by a null default (PHP 8.4 deprecates this)
1Check
Search for typed parameters whose only way to accept null is the default value.
grep -rnE "function .*\b[A-Za-z_\\]+ \$[a-z_]+ = null" src/2Fix
State the nullable type explicitly. The manual says implicit nullability through a null default is not recommended and is deprecated since PHP 8.4.
// before
function f(C $c = null) {}
// after
function f(?C $c = null) {}3Verify
Run the file under PHP 8.4 with all errors on.
php -d error_reporting=E_ALL -d display_errors=1 -l src/f.phpConfirmed by php.net
How do I stop it coming back?
- Declare nullable types explicitly (?T) wherever null is a legal input.
- Run tests and CI with error_reporting set to E_ALL so deprecations show up before an upgrade.
- Read the 8.x migration pages before raising the PHP version in production.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
Related fixes
Back end
Android gets HTML instead of JSON from a PHP API
org.json.JSONException: Value <br of type java.lang.String cannot be converted to JSONObject
The response body is not JSON.
2 causes, each with a fixBack end
Apache returns 403 when a URL contains %3F
a request like /page%3Fname=test is refused while /page?name=test works
Recent Apache httpd blocks a rewrite when the request contains an encoded question mark (%3F) and the rewritten target has a literal ?.
2 causes, each with a fixBack end
Apache returns 500 with Premature end of script headers
500 Internal Server Error
Apache ran your script, but the script printed no valid HTTP header before its output.
3 causes, each with a fixBack end
Apache returns 503 or 504 because PHP-FPM did not answer in time
Error dispatching request
Apache sent the request to PHP-FPM and gave up waiting.
3 causes, each with a fixBack end
AWS SDK for PHP cannot get credentials from the instance profile metadata server
Error retrieving credentials from the instance profile metadata server.
The SDK tries the EC2 instance metadata service when it has no valid credentials from anywhere earlier in its chain.
4 causes, each with a fixBack end
AWS SDK for PHP rejects requests: the signature is from the future
Signature not yet current: {date} is still later than {date}
AWS compares the timestamp in your signed request with its own clock.
2 causes, each with a fix