Uncaught `UnexpectedValueException` from `Methods::getStorage()` during taint analysis — method identifier case-normalized against a declaring class that doesn't have it

[Leon-Rakuten]

Summary

Running psalm --taint-analysis over a production PHP codebase crashes the
entire run with an uncaught UnexpectedValueException raised deep inside
Psalm\Internal\Codebase\Methods::getStorage() (line 1154 on 6.16.1) instead of
reporting an UndefinedMethod-style finding.

The crash kills the whole scan with no report produced, which is fatal for
pipeline usage (we run Psalm's taint mode as one stage of a multi-tool
security scan).

Environment

• Psalm: 6.16.1 (build f1f5de5), installed via composer global
• PHP: 8.x CLI (macOS arm64)
• Command: psalm --taint-analysis --output-format=json --report=<path> --no-progress --config=<generated psalm.xml>

Error

Uncaught Amp\Parallel\Worker\TaskFailureException: UnexpectedValueException thrown in context
with message "$storage should not be null for
App\Authenticate\Manager\LdapManagerUserInterface::setusername" and code "0"
in .../vimeo/psalm/src/Psalm/Internal/Codebase/Methods.php:1154

Stack trace in context:
#0 .../Psalm/Internal/Codebase/Methods.php(1154): Methods->getStorage(...)
#1 .../Psalm/Internal/Analyzer/MethodAnalyzer.php(73): Psalm\Internal\Codebase\Methods->getStorage(Object(Psalm\Internal\MethodIdentifier))
#2 .../Psalm/Internal/Analyzer/InterfaceAnalyzer.php(161): MethodAnalyzer->__construct(...)
#3 .../Psalm/Internal/Analyzer/FileAnalyzer.php(192): InterfaceAnalyzer->analyze()
#4 .../Psalm/Internal/Codebase/Analyzer.php(1486): FileAnalyzer->analyze()
#5 .../Psalm/Internal/Fork/AnalyzerTask.php(28): Analyzer::analysisWorker(...)
...
(Psalm 6.16.1@f1f5de594dc76faf8784e02d3dc4716c91c6f6ac crashed due to an uncaught Throwable)

Context (anonymized excerpts from the affected codebase)

The lookup that crashes is for setusername — note the lowercase method
name in the message. In the analyzed code, the same name exists in different
casing across related types:

// OpsUserInterface.php — declares the method as setUserName (capital N)
interface OpsUserInterface
{
    public function setUserName(string $username): self;
}

// OpsUser.php — implements it as setUsername (lowercase n), legal PHP
final class OpsUser implements OpsUserInterface
{
    public function setUsername(string $username): OpsUserInterface { ... }
}

// OpsUserProvider.php — property docblocks and a fluent call chain
/**
 * @var LdapManagerUserInterface
 */
private $ldapManager;

/**
 * @var OpsUserInterface
 */
private $userClass;

// ...
$user = $this->userClass;
$user
    ->setUsername($username)
    ->setManagerId($managerId)
    ->setDn($lm->getDn())
    ...

LdapManagerUserInterface is a separate interface that does not declare
any setUsername variant — yet Psalm constructs MethodIdentifier for
LdapManagerUserInterface::setusername (case-normalized) during interface
analysis, and getStorage() throws because that key has no storage.

Expected behavior

A method identifier that fails to resolve against a declaring class should
surface as a normal analyzer finding (e.g. UndefinedMethod /
MixedMethodCall-style) — or at most a skipped file with a warning. It must
never escape as an uncaught Throwable that terminates the entire analysis.

The root question is also worth looking at on its own: PHP method dispatch is
case-insensitive, so the interface/implementer casing mismatch above is valid
code; the storage lookup appears to lose the case-insensitive guarantee when
the identifier is normalized against a declaring class that received the
method via a case-mismatched implementation.

Notes

• We could not reduce this below the multi-file Laravel-style project context;
  the excerpts above are the closest involved types. Happy to share a fuller
  reproduction project privately or test a patch against the original codebase.
• Reproduced twice with identical stacks (identical run completed normally
  after the involved docblock annotations were corrected).

[psalm-github-bot]

Hey @Leon-Rakuten, can you reproduce the issue on https://psalm.dev? These will be used as phpunit tests when implementing the feature or fixing this bug.

[Leon-Rakuten]

Why psalm.dev can't host this repro

I tried to reduce it to a playground snippet and could not — the crash needs
the full multi-file project context (two sibling Symfony applications sharing
one scan root, so the same AcmeDemoBundle\* classes/interfaces are
declared twice with diverged shapes — one copy's interface methods differ
in signature and presence from the other's). Single-file consolidations and
small extractions of the involved classes run clean; the crash only appears
when Psalm analyzes the full duplicated tree with taint analysis on.

What I can offer instead

A much tighter characterization than the original report, from a fresh
investigation (Psalm 6.16.1, PHP 8.x CLI, macOS):

• Command: psalm --taint-analysis over the duplicated tree (plain
  psalm without taint mode does not crash).
• Failure: uncaught UnexpectedValueException: $storage should not be null for AcmeDemoBundle\...\LdapConnectionInterface::changepassword
  in Methods.php:1154, via MethodAnalyzer::__construct ←
  InterfaceAnalyzer — kills the whole run with exit code 1 and no report
  (fatal for pipeline use).
• Nondeterministic victim: the failing lookup varies run to run over the
  same input (observed LdapManagerUserInterface::setusername and
  LdapConnectionInterface::changepassword; note the lowercased method
  names in the message — the declarations use mixed case, and PHP method
  dispatch is case-insensitive).
• Not a parallel race: --threads=1 crashes too; the run-to-run variance
  comes from analysis ordering, not worker concurrency.
• Cache is irrelevant: crashes with a cold cache, a warm cache, and with
  --no-cache.
• Crash rate: roughly 2 of 3 runs on the affected tree; the third
  completes normally.

The closest minimal shape (divergent duplicate interface declarations plus
an implementer whose method casing differs from the interface) runs clean on
its own, which is why I'd rather not post a snippet that wastes your time.

I can share the actual two-application tree as a private reproducer archive,
and I'm happy to test any patch against it. Just let me know the preferred
channel.