CodeIgniter - unable to load requested class

CodeIgniter - unable to load requested class

  1. Blog
  2. 15 November 2026
  3. 3 min read

Stefan Bogdanescu

Founder & Senior Architect

CodeIgniter - Unable to Load Requested Class: The Case of phpass on Linux

When deploying a CodeIgniter application from a local development environment like MAMP to a production server such as Ubuntu with Apache2, environment-specific failures often surface suddenly. A common culprit is the "Unable to load the requested class" error, specifically when attempting to autoload a library named phpass. While many online resources suggest checking file paths or capitalization, these factors are typically not the issue if the local setup works perfectly. The root cause here lies in how CodeIgniter resolves class names and the strict requirements of its autoloading mechanism.

The error message explicitly states: "Unable to load the requested class: Phpass". In CodeIgniter's autoload configuration, the key resides in the application/config/autoload.php file where you define $autoload['libraries'] = array('database', 'phpass');. At first glance, this looks correct. However, CodeIgniter follows a strict naming convention for libraries located in the application/libraries directory: the filename must be capitalized to match the class name exactly.

If your file is named phpass.php but the class inside is declared as class phpass, you are violating PHP's case sensitivity rules relative to CodeIgniter's expectation. On Windows-based systems like MAMP, the operating system is generally case-insensitive. It will happily serve a request for phpass.php regardless of whether you reference it as Phpass, phpass, or PHPASS. This masks the underlying mismatch between the framework's expectations and your implementation.

Linux file systems, however, are strictly case-sensitive. When Apache2 on Ubuntu attempts to load the class Phpass (as inferred from the error message which often normalizes names to PascalCase for internal lookup) against a file named phpass.php, the system cannot find it because Phpass.php does not exist. The fix requires aligning the filename with the case of the class declaration or ensuring the class name matches the filename convention.

Furthermore, there is a critical architectural detail in the provided code snippet regarding how the library initializes. The constructor attempts to include an external file using a relative path:

if (!file_exists($path = dirname(__FILE__) . '/../vendor/PasswordHash.php')) {
    show_error('The phpass class file was not found.');
}
include ($path);

This approach relies on the existence of a vendor directory relative to the library file. If this dependency is missing or if the path resolution fails differently under Apache's document root context, it could compound the loading issue. However, the primary blocker remains the filename mismatch.

To resolve this without rewriting the entire class structure, you have two viable options:

  1. Rename the file: Change phpass.php to Phpass.php. This aligns with CodeIgniter's standard convention where the first letter of the filename matches the first letter of the class name (assuming the class is named Phpass).
  2. Refactor the class name: If you prefer to keep the lowercase filename, you must ensure the class declaration inside matches the exact casing expected by your autoloader logic, though CodeIgniter's internal autoloader generally expects the filename to be the primary key for case-insensitive environments and strictly case-sensitive for others.

Additionally, verify that your application/libraries folder is indeed being scanned. If you moved the file from a subdirectory like application/libraries/PasswordHash/ without updating the autoload path or including it explicitly, the framework will look only in the root libraries folder. Ensure the physical location matches the logical expectation defined in the configuration.

Finally, consider the trade-off of using external vendor files within a library constructor. While convenient for prototyping, relying on relative paths to vendor directories can lead to path resolution errors when the application is moved between servers. It is often more robust to load these dependencies via Composer or place them directly in a standard libraries folder structure where the autoloader can find them without manual include statements inside constructors. This ensures consistency regardless of the server environment, preventing the kind of "works on MAMP but not Ubuntu" discrepancies that plague production deployments.

Our network