Installation and Configuration Trouble-shooting

Trouble-shooting Resources For installations problems, first make sure that you're read and followed the step-by-step directions for your type of installation: Drupal Installation Guide, Joomla Installation Guide, or Standalone Installation Guide.   You can often find solutions to your issue by searching the installation support section of the community forum OR the community mailing list archives. You can also check out the Installation section of our FAQs.   If you don't find an answer to your problem in those places, the next step is to post a support request on the forum.

"DB_DataObject Error: DB Error: connect failed"

If you get this error on a new Drupal/CiviCRM installation, you may have skipped the step of running CiviCRM's installation script. You can not install CiviCRM using the standard Drupal module installer. Review the installation instructions here.

"Could not find valid Key"

If you are getting this error when submitting a form (search or adding / editing records), check the following:

• Ensure cookies are enabled on browser. Like most web applications, CiviCRM can not function properly with cookies disabled.
• Ensure your configuration settings are using the same "machine name" for CiviCRM and your CMS (Drupal or Joomla!). For example, you will have problems if CiviCRM is configured to use http://example.com as it's BASE_URL and you CMS is using http://www.example.com. You can use an .htaccess entry to redirect to the configured URL if needed (i.e. push all users to http://www.example.com even if they hit http://example.com).
  3. For Drupal sites, ensure that uid = 0 exists in your Drupal users table. This is required for anonymous access to CiviCRM pages and forms to work properly.
  4. For Drupal sites, ensure that Drupal sessions table uses UTF8 collation, AND that the session column in this table is of SQL type longtext in the schema. You can check both of these in phpMyAdmin, or issue these commands from mysql command line:

"Failed to initialize storage module: user" fatal error message (new installs)

If you see this error, you may need to modify the session.save_handler method for your site. Check with your hosting provider for the recommended way to do this. More info at this forum post.

Using the Built-in Debugging Tools

CiviCRM provides several URL-param debug settings which can help debug and resolve problems such as corrupt sessions and obsolete template caches. In order to use these URL parameters, you must first enable debugging from Administer CiviCRM » Global Settings » Debugging.

Do NOT Leave Debug Turned On in Production Sites It is critical that the DEBUG features are disabled in production sites. When debug is enabled - system paths and other internal settings may be exposed to browsers.

Debug Commands

• Smarty Debug Window - Loads all variables available to the current page template into a pop-up
  window. To trigger, add '&smartyDebug=1' to any CiviCRM URL query string.

• Session Reset - Resets all values in your client session. To trigger, add '&sessionReset=2'

• Directory Cleanup - Empties template cache and/or upload file folders.
  • To empty template cache (civicrm/templates_c folder), add '&directoryCleanup=1'
  • To remove temporary upload files (civicrm/upload folder), add '&directoryCleanup=2'
  • To cleanup both, add '&directoryCleanup=3'

• Stack Trace - To display stack trace at the top of the page when an error occurs, set Enable Backtrace from Administer CiviCRM » Global Settings » Debugging.

Resolving RELAY-DENIED Errors When Trying to Send Emails to Contacts

(under construction)

Configuring PHP to Handle Import Files from/on Macintosh Computers

In order for CiviCRM to properly handle CSV import files created on Macs, you may need to update a PHP setting for detecting line endings. The symptom of this problem is that the "Import Contacts: Match Fields" step shows the file as one big record - rather than recognizing the end of each row.

• Open /opt/local/etc/php.ini in your favorite editor (you may need root privileges to do this).
• Look for the following setting in the Fopen wrappers section (near line 525):

• If this line is commented out, or set to Off, change the value to On as shown above.
• Stop and start your local instance of Apache

Database version inconsistencies / upgrade problems

Download and run Database Troubleshooting Tools to test the current state of the database and provides a diagnosis. The tools suite also includes a repair facility.

Windows XP SP3: Problem setting the /sites/default/files directory permissions so it is writable

There is a weird glitch that can happen under Windows XP (SP3) (and perhaps other Windows OS versions): if you try to change the permissions for a file or directory, they won't 'stick.' For example, if you go to your <yoursite>/sites/default/files directory and right click on it and bring up the Properties dialog, you can see the permissions for the directory. If this is set to read only, you will get an error message when you install CiviCRM telling that it needs to be writable. If you click on the "Read Only" checkbox so that it is not checked and then OK your change, the permission should be changed. (The directory should now be writable.) However, sometimes this change will not actually take effect. You have to make the change using the ATTRIB command in a command prompt window. Open a command prompt window and go to the <yoursite>/sites/default directory. Type "help attrib" to get help using the attrib command and then enter the appropriate arguments to set the /files directory permissions (attributes) so that it's writeable. This will usually invovle the "-R" attribute and the "/D" argument.