Can't locate package XXX for @XXX::ISA

You may see this error and think that package XXX can't be found in @INC and then be stumped when you find that module XXX.pm is in @INC.

The problem here is that "Can't locate package XXX" is not refering to the module XXX.pm and is not indicating that this module can't be found. It is referring to the package XXX and it is indicating that the stash of the package XXX isn't defined. This usually results from the module that defines the package not having been loaded (by use, require or do).

While there is often a one-to-one correspondence between them, packages and modules are not the same thing. A module is a file containing Perl code. A package is a namespace with its own stash containing the names in the namespace.

When @ISA is being processed, each package in the @ISA list must already be loaded (by use or require or do or whatever). If the stash for the package namespace isn't defined, then this error is produced.

The solution is to load the module that provides the package before including the package in @INC.