Diagnostics
From Textpattern CMS User Documentation
Diagnostics provide information about problems that might exist upon initially installing - or upgrading to - a new version of Textpattern. The panel and some of the common potential errors you might see are described below.
Contents |
Panel Controls
Diagnostics Troubleshooting
The diagnostics are presented as a series of "Pre-Flight" items to check, and are listed at the top of the page in red text. It's recommended you troubleshoot diagnostics after every new installation and upgrade. Unfortunately, not all errors are in fact errors, which makes troubleshooting a bit more confusing.
Further, errors can appear in a cascading way; in other words, some errors may appear because of an error that appears before it. Thus, addressing diagnostics in top-down fashion can sometimes kill two or more problems at a time.
Errors and Explanations
- path_to_site doesn't match document_root [ /home/yourserveralias/public_html ]:
- Could mean one of two problems: either you do not have the right "Site URL" path set in Basic Preferences, or in the case of upgrading, you still need to update your index.php and .htaccess files (see next diagnostic).
- Could be a false error: Symlinks, unfortunately, cannot be correctly recognized, so you might get this error even though there is not really a problem. Unless you are having actual problems you shouldn't worry too much about this.
- /index.php is inaccessible:
- Suggests your index.php file is not available, is not the right version, or (as in the previous diagnostic) that your Site URL is wrong. It can be the case that the index.php file does not directly download during an initial upgrade (for whatever reason). Whether you need to add a new index.php file or revise it the latest version, get the latest copy of index.php from the current repository for Textpattern development.
- path_to_site is inaccessible:
- Suggests either one or both of the previous diagnostics are a problem. Follow the troubleshooting procedures for them accordingly.
- image directory is read-only: /images:
- Indicates you need to change the permissions on your images folder before you can add any images to it
- For removing this error without doubt, change its permissions to "all can read and write" (chmod 777) BUT be aware of the security implications of doing so. In some (most) situations and hosting environments, chmod 755 (or even 711) are good enough depending on which Apache directives you are using.
- You may see similar error messages for other folders, like for "/files". The same solution applies.
- .htaccess file is missing:
- Involves the .htaccess file and usually appears if you are trying to use one of the "clean" URL settings, and you have one of the previous diagnostic issues with the wrong path or missing index.php file. Take care of those issues first and then see if this diagnostic disappears. If that does not work, then check to see if you even have an .htaccess file. If the file is there, then either do the previous suggestion to replace it, or click the help link appearing next to this particular diagnostic and replace the contents of your existing .htaccess file with the indicated rewrite rules in the help dialog.
- /usr/home/your-server-account-name/public_html/textpattern/setup/ still exists
- Indicates the setup folder still exists. If you don't delete it, there will be no adverse effect on Textpattern, but removing it is a good idea to improve security so that others cannot run setup again... plus it will remove the diagnostic error.
- Clean URL test failed:
- This is not necessarily an error that will prevent your site from working. It could be caused by the PHP configuration setting of allow_url_fopen or some other hosting issue. See this FAQ.
Other Error Help Locations
FAQ Diagnostics
Check the FAQ Diagnostics Section.
Support Forum
Last but not least, ask in the Textpattern Forum.
No matter where you find resolution to a diagnostic error, please consider coming back here to record the errors/solutions in the list above for benefit of future readers.
