PHP Errors and Exceptions
Detailed information about basic PHP errors on your Pantheon Drupal or WordPress site.
There are three basic kinds of PHP errors:
- Notice: room for improvement; typically unset variables or missing array keys.
- Warning: errors will probably occur if not addressed.
- Error: fatal, execution terminated. Often known as the "white screen of death".
For more in-depth information, see Error Handling and Logging.
Each of the PHP errors are handled differently depending on the site environment. On Dev, they are shown directly to the user in the browser. On Test and Live, PHP errors are not displayed to users, but they'll still be logged. Notices and warnings are logged in the database logs if
db\_log is enabled for Drupal. The PHP constants
WP_DEBUG_LOG can be enabled for WordPress to save errors to wp-content/debug.log. PHP errors are also logged on the application server at
Here's a breakdown of what errors are shown and where:
To learn more about PHP error logs, see Log Files on Pantheon.
An error, no matter what severity, is a problem that needs to be addressed. Any PHP error, even a notice, will drastically reduce the speed of PHP execution. Even if you don't see the error in your browser, and even if you explicitly disable logging, every single PHP error will slow your site down.
If database logging is enabled, your site will be even slower, requiring a database write for every error. However, disabling logging does not address the problem, it only hides the symptom.
Best practice is to fix every notice, warning, and error as you discover them. If they're in an extension (WordPress plugin or Drupal module), roll a patch and submit it to the project's issue queue.
See this stackoverflow thread for some more details, including benchmarks that compare the differences between suppressing notices and actually eliminating the root cause.
A PHP exception is a mechanism for defining error conditions and how to handle them. For more details on Exceptions, see the PHP documentation on Exceptions..
PHP Exceptions are errors, and depending on the severity and whether they are handled correctly can crash your site. As Exceptions are created in code and not by PHP itself, they are not logged in the PHP error log file and will not be visible in the Pantheon Dashboard. By default, Drupal will log exceptions to Watchdog.
Undefined Function Error
However, when a PHP file is requested directly (e.g.,
index.php file and the bootstrap process are skipped. Instead, the PHP file is executed on it's own and any function included but not defined by the file will cause a
Call to undefined function fatal error.
For example, in the following error PHP reports the
phpfile.php file at line
xx for calling
some_function(), which has not yet been defined:
Call to undefined function [some_function()] in [path/to/phpfile.php:xx]
Use the following debugging techniques to investigate undefined function error messages:
- Search for the offending function elsewhere in the codebase to make sure it's defined somewhere in the project.
- Check the reported PHP file at full bootstrap. Rather than accessing the reported PHP file directly (e.g.,
https://example.com/path/to/phpfile.php), browse to a page that includes the file (e.g.,
https://example.com/some-page/) to see if the same error occurs with the site fully bootstrapped.
nginx-access.logfor requests to the reported PHP file.
If you see direct requests to PHP files causing fatal undefined function errors (often caused by bot traffic), use the
pantheon.yml configuration file to set protected web paths. For details, see Pantheon YAML Configuration Files. This stops the file from being web accessible while keeping the file available to PHP during bootstrap. When accessed directly, protected paths and files return a 403 Access Denied server response.
We also recommend submitting a sitemap and instructing bots to only crawl designated paths set in
robots.txt. For details, see Bots and Indexing on Pantheon.
Undefined Index Notices
When you import your site or enable some new modules, PHP notices may be reported on your Dev site that have never been reported before. These notices are now being made apparent because of the Dev environment's strict error reporting level.
An example notice might look like this:
Notice: Undefined index: description in theme_imagefield_image_imagecache_lightbox2() (line 163 of /srv/bindings/xxxxxxxxx/code/sites/all/modules/contrib/lightbox2/lightbox2.formatter.inc)..
Why is PHP reporting this?
Variable declaration is not required by PHP, but is a recommended practice that can help to avoid security vulnerabilities or bugs if one forgets to provide a value to a variable that be used later on. PHP issues an E_NOTICE, a very low-level error, as a reminder.
No one is going to twist your arm about addressing these notices, but Pantheon believes that surfacing them in the Development environment will help developers address potential problems in the future before they can occur by following best practices.
Fatal Error: require_once(): Failed Opening Required
The require_once() function simply checks to see if a file has been included already, if it has not, then it will be included when checked.
When this error surfaces, it simply means that the file in question is not where it should be. For example, the error will look something like this:
Fatal error: require_once(): Failed opening required ‘/srv/bindings/xxxxx/code/sites/all/modules/redis/redis.autoload.inc’ (include_path=‘.:/usr/share/pear:/usr/share/php’) in /srv/bindings/xxxxxx/code/includes/bootstrap.inc on line 2394
To fix this error, look for the correct path to the file and update the require_once().
If you are encountering intermittent notices that are not behaving as described on this page, see Debug Intermittent PHP 7 Notices for additional information. This is not common.