FAQs and Other Troubleshooting

Below are some commonly asked questions about Elgg.


See also

Getting Help

“Plugin cannot start and has been deactivated” or “This plugin is invalid”

This error is usually accompanied by more details explaining why the plugin is invalid. This is usually caused by an incorrectly installed plugin.

If you are installing a plugin called “test”, there will be a test directory under mod. In that test directory there needs to be a composer.json file /mod/test/composer.json.

If this file does not exist, it could be caused by:
  • installing a plugin to the wrong directory

  • creating a directory under /mod that does not contain a plugin

  • a bad ftp transfer

  • unzipping a plugin into an extra directory (myplugin.zip unzips to myplugin/myplugin)

  • incompatible plugin

If you are on a Unix-based host and the files exist in the correct directory, check the permissions. Elgg must have read access to the files and read + execute access on the directories.

White Page (WSOD)

A blank, white page (often called a “white screen of death”) means there is a PHP syntax error. There are a few possible causes of this:
  • corrupted file - try transfering the code again to your server

  • a call to a php module that was not loaded - this can happen after you install a plugin that requires a specific module.

  • bad plugin - not all plugins have been written to the same quality so you should be careful which ones you install.

To find where the error is occurring, change the .htaccess file to display errors to the browser. Set display_errors to 1 and load the same page again. You should see a PHP error in your browser. Change the setting back once you’ve resolved the problem.


If you are using the Developer’s Tools plugin, go to its settings page and make sure you have “Display fatal PHP errors” enabled.

If the white screen is due to a bad plugin, remove the latest plugins that you have installed by deleting their directories and then reload the page.


You can temporarily disable all plugins by creating an empty file at mod/disabled. You can then disable the offending module via the administrator tools panel.

If you are getting a WSOD when performing an action, like logging in or posting a blog, but there are no error messages, it’s most likely caused by non-printable characters in plugin code. Check the plugin for white spaces/new lines characters after finishing php tag (?>) and remove them.

Page not found

If you have recently installed your Elgg site, the most likely cause for a page not found error is that mod_rewrite is not setup correctly on your server. There is information in the Install Troubleshooting page on fixing this. The second most likely cause is that your site url in your database is incorrect.

If you’ve been running your site for a while and suddenly start getting page not found errors, you need to ask yourself what has changed. Have you added any plugins? Did you change your server configuration?

To debug a page not found error:

  • Confirm that the link leading to the missing page is correct. If not, how is that link being generated?

  • Confirm that the .htaccess rewrite rules are being picked up.

Login token mismatch

If you have to log in twice to your site and the error message after the first attempt says there was a token mismatch error, the URL in Elgg’s settings does not match the URL used to access it. The most common cause for this is adding or removing the “www” when accessing the site. For example, www.elgg.org vs elgg.org. This causes a problem with session handling because of the way that web browsers save cookies.

To fix this, you can add rewrite rules. To redirect from www.elgg.org to elgg.org in Apache, the rules might look like:

RewriteCond %{HTTP_HOST} .
RewriteCond %{HTTP_HOST} !^elgg\.org
RewriteRule (.*) http://elgg.org/$1 [R=301,L]

Redirecting from non-www to www could look like this:

RewriteCond %{HTTP_HOST} ^elgg\.org
RewriteRule ^(.*)$ http://www.elgg.org/$1 [R=301,L]

If you don’t know how to configure rewrite rules, ask your host for more information.

Form is missing __token or __ts fields

All Elgg actions require a security token, and this error occurs when that token is missing. This is either a problem with your server configuration or with a 3rd party plugin.

If you experience this on a new installation, make sure that your server is properly configured and your rewrite rules are correct. If you experience this on an upgrade, make sure you have updated your rewrite rules either in .htaccess (Apache) or in the server configuration.

If you are experiencing this, disable all 3rd party plugins and try again. Very old plugins for Elgg don’t use security tokens. If the problem goes away when plugins are disabled, it’s due to a plugin that should be updated by its author.

Maintenance mode

To take your site temporarily offline, go to Administration -> Utilities -> Maintenance Mode. Complete the form and hit save to disable your site for everyone except admin users.

Missing email

If your users are reporting that validation emails are not showing up, have them check their spam folder. It is possible that the emails coming from your server are being marked as spam. This depends on many factors such as whether your hosting provider has a problem with spammers, how your PHP mail configuration is set up, what mail transport agent your server is using, or your host limiting the number of email that you can send in an hour.

If no one gets email at all, it is quite likely your server is not configured properly for email. Your server needs a program to send email (called a Mail Transfer Agent - MTA) and PHP must be configured to use the MTA.

To quickly check if PHP and an MTA are correctly configured, create a file on your server with the following content:

$address = "your_email@your_host.com";

$subject = 'Test email.';

$body = 'If you can read this, your email is working.';

echo "Attempting to email $address...<br />";

if (mail($address, $subject, $body)) {
        echo 'SUCCESS!  PHP successfully delivered email to your MTA.  If you don\'t see the email in your inbox in a few minutes, there is a problem with your MTA.';
} else {
        echo 'ERROR!  PHP could not deliver email to your MTA.  Check that your PHP settings are correct for your MTA and your MTA will deliver email.';

Be sure to replace “your_email@your_host.com” with your actual email address. Take care to keep quotes around it! When you access this page through your web browser, it will attempt to send a test email. This test will let you know that PHP and your MTA are correctly configured. If it fails–either you get an error or you never receive the email–you will need to do more investigating and possibly contact your service provider.

Fully configuring an MTA and PHP’s email functionality is beyond the scope of this FAQ and you should search the Internet for more resources on this. Some basic information on php parameters can be found on PHP’s site

Server logs

Most likely you are using Apache as your web server. Warnings and errors are written to a log by the web server and can be useful for debugging problems. You will commonly see two types of log files: access logs and error logs. Information from PHP and Elgg is written to the server error log.

  • Linux – The error log is probably in /var/log/httpd or /var/log/apache2.

  • Windows - It is probably inside your Apache directory.

  • Mac OS - The error log is probably in /var/log/apache2/error_log

If you are using shared hosting without ssh access, your hosting provider may provide a mechanism for obtaining access to your server logs. You will need to ask them about this.

How does registration work?

With a default setup, this is how registration works:

  1. User fills out registration form and submits it

  2. User account is created and disabled until validated

  3. Email is sent to user with a link to validate the account

  4. When a user clicks on the link, the account is validated

  5. The user can now log in

Failures during this process include the user entering an incorrect email address, the validation email being marked as spam, or a user never bothering to validate the account.

User validation

By default, all users who self-register must validate their accounts through email. If a user has problems validating an account, you can validate users manually by going to Administration -> Users -> Unvalidated.

You can remove this requirement by deactivating the User Validation by Email plugin.


Removing validation has some consequences: There is no way to know that a user registered with a working email address, and it may leave you system open to spammers.

Manually add user

To manually add a user, under the Administer controls go to Users. There you will see a link title “Add new User”. After you fill out the information and submit the form, the new user will receive an email with username and password and a reminder to change the password.


Elgg does not force the user to change the password.

I’m making or just installed a new theme, but graphics or other elements aren’t working

Make sure the theme is at the bottom of the plugin list.

Clear your browser cache and reload the page. To lighten the load on the server, Elgg instructs the browser to rarely load the CSS file. A new theme will completely change the CSS file and a refresh should cause the browser to request the CSS file again.

If you’re building or modifying a theme, make sure you have disabled the simple and system caches. This can be done by enabling the Developer Tools plugin, then browsing to Administration -> Develop -> Settings. Once you’re satisfied with the changes, enable the caches or performance will suffer.

Changing profile fields

Within the Administration settings of Elgg is a page for replacing the default profile fields. Elgg by default gives the administrator two choices:

  • Use the default profile fields

  • Replace the default with a set of custom profile fields

You cannot add new profile fields to the default ones. Adding a new profile field through the replace profile fields option clears the default ones. Before letting in users, it is best to determine what profile fields you want, what field types they should be, and the order they should appear. You cannot change the field type or order or delete fields after they have been created without wiping the entire profile blank.

More flexibility can be gained through plugins. There is at least two plugins on the community site that enable you to have more control over profile fields. The Profile Manager plugin has become quite popular in the Elgg community. It lets you add new profile fields whenever you want, change the order, group profile fields, and add them to registration.

Changing registration

The registration process can be changed through a plugin. Everything about registration can be changed: the look and feel, different registration fields, additional validation of the fields, additional steps and so on. These types of changes require some basic knowledge of HTML, CSS, PHP.

Another option is to use the Profile Manager plugin that lets you add fields to both user profiles and the registration form.

Create the plugin skeleton

Plugin skeleton

Changing registration display

Override the account/forms/register view

Changing the registration action handler

You can write your own action to create the user’s account

How do I change PHP settings using .htaccess?

You may want to change php settings in your .htaccess file. This is especially true if your hosting provider does not give you access to the server’s php.ini file. The variables could be related to file upload size limits, security, session length, or any number of other php attributes. For examples of how to do this, see the PHP documentation on this.

HTTPS login turned on accidently

If you have turned on HTTPS login but do not have SSL configured, you are now locked out of your Elgg install. To turn off this configuration parameter, you will need to edit your database. Use a tool like phpMyAdmin to view your database. Select the config table and delete the row that has the name https_login.

Using a test site

It is recommended to always try out new releases or new plugins on a test site before running them on a production site (a site with actual users). The easiest way to do this is to maintain a separate install of Elgg with dummy accounts. When testing changes it is important to use dummy accounts that are not admins to test what your users will see.

A more realistic test is to mirror the content from your production site to your test site. Following the instructions for duplicating a site. Then make sure you prevent emails from being sent to your users. You could write a small plugin that redirects all email to your own account (be aware of plugins that include their own custom email sending code so you’ll have to modify those plugins). After this is done you can view all of the content to make sure the upgrade or new plugin is functioning as desired and is not breaking anything. If this process sounds overwhelming, please stick with running a simple test site.

500 - Internal Server Error

What is it?

A 500 - Internal Server Error means the web server experienced a problem serving a request.

Possible causes

Web server configuration

The most common cause for this is an incorrectly configured server. If you edited the .htaccess file and added something incorrect, Apache will send a 500 error.

Permissions on files

It could also be a permissions problem on a file. Apache needs to be able to read Elgg’s files. Using permissions 755 on directories and 644 on files will allow Apache to read the files.

When I upload a photo or change my profile picture I get a white screen

Most likely you don’t have the PHP GD library installed or configured properly. You may need assistance from the administrator of your server.

CSS is missing

Wrong URL

Sometimes people install Elgg so that the base URL is localhost and then try to view the site using a hostname. In this case, the browser won’t be able to load the CSS file. Try viewing the source of the web page and copying the link for the CSS file. Paste that into your browser. If you get a 404 error, it is likely this is your problem. You will need to change the base URL of your site.

Syntax error

Elgg stores its CSS as PHP code to provide flexibility and power. If there is a syntax error, the CSS file served to the browser may be blank. Disabling non-bundled plugins is the recommended first step.

Rewrite rules errors

A bad .htaccess file could also result in a 404 error when requesting the CSS file. This could happen when doing an upgrade and forgetting to also upgrade .htaccess.

Should I edit the database manually?


No, you should never manually edit the database!

Will editing the database manually break my site?


Can I add extra fields to tables in the database?

(AKA: I don’t understand the Elgg data model so I’m going to add columns. Will you help?)

No, this is a bad idea. Learn the data model and you will see that unless it’s a very specific and highly customized installation, you can do everything you need within Elgg’s current data model.

I want to remove users. Can’t I just delete them from the elgg_entities table?

No, it will corrupt your database. Delete them through the site.

I want to remove spam. Can’t I just search and delete it from the elgg_entities table?

No, it will corrupt your database. Delete it through the site.

Someone on the community site told me to edit the database manually. Should I?

Who was it? Is it someone experienced with Elgg, like one of the core developers or a well-known plugin author? Did he or she give you clear and specific instructions on what to edit? If you don’t know who it is, or if you can’t understand or aren’t comfortable following the instructions, do not edit the database manually.

I know PHP and MySQL and have a legitimate reason to edit the database. Is it okay to manually edit the database?

Make sure you understand Elgg’s data model and schema first. Make a backup, edit carefully, then test copiously.

Internet Explorer (IE) login problem

Canonical URL

IE does not like working with sites that use both http://example.org and http://www.example.org. It stores multiple cookies and this causes problems. Best to only use one base URL. For details on how to do this see Login token mismatch error.

Chrome Frame

Using the chrome frame within IE can break the login process.

Emails don’t support non-Latin characters

In order to support non-Latin characters, (such as Cyrillic or Chinese) Elgg requires multibyte string support to be compiled into PHP.

On many installs (e.g. Debian & Ubuntu) this is turned on by default. If it is not, you need to turn it on (or recompile PHP to include it). To check whether your server supports multibyte strings, check phpinfo.

Session length

Session length is controlled by your php configuration. You will first need to locate your php.ini file. In that file will be several session variables. A complete list and what they do can be found in the php manual.

File is missing an owner

There are three causes for this error. You could have an entity in your database that has an owner_guid of 0. This should be extremely rare and may only occur if your database/server crashes during a write operation.

The second cause would be an entity where the owner no longer exists. This could occur if a plugin is turned off that was involved in the creation of the entity and then the owner is deleted but the delete operation failed (because the plugin is turned off). If you can figure out entity is causing this, look in your entities table and change the owner_guid to your own and then you can delete the entity through Elgg.


Reed the section “Should I edit the database manually?”. Be very carefull when editing the database directly. It can break your site. Always make a backup before doing this.


Database Validator plugin will check your database for these causes and provide an option to fix them. Be sure to backup the database before you try the fix option.

No images

If profile images, group images, or other files have stopped working on your site it is likely due to a misconfiguration, especially if you have migrated to a new server.

These are the most common misconfigurations that cause images and other files to stop working.

Wrong path for data directory

Make sure the data directory’s path is correct in the Site Administration admin area. It should have a trailing slash.

Wrong permissions on the data directory

Check the permissions for the data directory. The data directory should be readable and writeable by the web server user.

Migrated installation with new data directory location

If you migrated an installation and need to change your data directory path, be sure to update the SQL for the filestore location as documented in the Duplicate Installation instructions.

Deprecation warnings

If you are seeing many deprecation warnings that say things like

Deprecated in 1.7: extend_view() was deprecated by elgg_extend_view()!

then you are using a plugin that was written for an older version of Elgg. This means the plugin is using functions that are scheduled to be removed in a future version of Elgg. You can ask the plugin developer if the plugin will be updated or you can update the plugin yourself. If neither of those are likely to happen, you should not use that plugin.

Javascript not working

If the user hover menu stops working or you cannot dismiss system messages, that means JavaScript is broken on your site. This usually due to a plugin having bad JavaScript code. You should find the plugin causing the problem and disable it. You can do this be disabling non-bundled plugins one at a time until the problem goes away. Another approach is disabling all non-bundled plugins and then enabling them one by one until the problem occurs again.

Most web browsers will give you a hint as to what is breaking the JavaScript code. They often have a console for JavaScript errors or an advanced mode for displaying errors. Once you see the error message, you may have an easier time locating the problem.

IP addresses in the logs are wrong

When your Elgg installation is behind a proxy server or loadbalancer the IP addresses logged in the System Log plugin can be wrong. It could show only the IP addresses for the proxy server.

In order to solve this you can configure the IP addresses of the proxy server as a trusted IP address and with that allow the system access to the correct IP address of your users.

In the settings.php file you can configure settings for $CONFIG->http_request_trusted_proxy_ips and $CONFIG->http_request_trusted_proxy_headers check the settings.php file for more information.


Is upgrade.php a security concern?

Upgrade.php is a file used to run code and database upgrades. It is in the root of the directory and doesn’t require a logged in account to access. On a fully upgraded site, running the file will only reset the caches and exit, so this is not a security concern.

If you are still concerned, you can either delete, move, or change permissions on the file until you need to upgrade.

Should I delete install.php?

This file is used to install Elgg and doesn’t need to be deleted. The file checks if Elgg is already installed and forwards the user to the front page if it is.


Filtering is used in Elgg to make XSS attacks more difficult. The purpose of the filtering is to remove Javascript and other dangerous input from users.

Filtering is performed through the function elgg_sanitize_input(). This function takes in a string and returns a filtered string. It triggers a sanitize, input event. By default Elgg comes with the htmLawed filtering code as a plugin. Developers can drop in any additional or replacement filtering code as a plugin.

The elgg_sanitize_input() function is called on any user input as long as the input is obtained through a call to get_input(). If for some reason a developer did not want to perform the default filtering on some user input, the get_input() function has a parameter for turning off filtering.


What should I use to edit php code?

There are two main options: text editor or integrated development environment (IDE).

Text Editor

If you are new to software development or do not have much experience with IDEs, using a text editor will get you up and running the quickest. At a minimum, you will want one that does syntax highlighting to make the code easier to read. If you think you might submit patches to the bug tracker, you will want to make sure that your text editor does not change line endings. If you are using Windows, Notepad++ is a good choice. If you are on a Mac, TextWrangler is a popular choice. You could also give TextMate a try.

Integrated Development Environment

An IDE does just what its name implies: it includes a set of tools that you would normally use separately. Most IDEs will include source code control which will allow you to directly commit and update your code from your cvs repository. It may have an FTP client built into it to make the transfer of files to a remote server easier. It will have syntax checking to catch errors before you try to execute the code on a server.

The two most popular free IDEs for PHP developers are Eclipse and NetBeans. Eclipse has two different plugins for working with PHP code: PDT and PHPEclipse.

I don’t like the wording of something in Elgg. How do I change it?

The best way to do this is with a plugin.

Create the plugin skeleton

Plugin skeleton

Locate the string that you want to change

All the strings that a user sees should be in the /languages directory or in a plugin’s languages directory (/mod/<plugin name>/languages). This is done so that it is easy to change what language Elgg uses. For more information on this see the developer documentation on Internationalization .

To find the string use grep or a text editor that provides searching through files to locate the string. (A good text editor for Windows is Notepad++ ) Let’s say we want to change the string “Add friend” to “Make a new friend”. The grep command to find this string would be grep -r "Add friend" *. Using Notepad++ , you would use the “Find in files” command. You would search for the string, set the filter to *.php, set the directory to the base directory of Elgg, and make sure it searches all subdirectories. You might want to set it to be case sensitive also.

You should locate the string “Add friend” in /languages/en.php. You should see something like this in the file:

'friend:add' => "Add friend",

This means every time Elgg sees friend:add it replaces it with “Add friend”. We want to change the definition of friend:add.

Override the string

To override this definition, we will add a languages file to the plugin that we built in the first step.

  1. Create a new directory: /mod/<your plugin name>/languages

  2. Create a file in that directory called en.php

  3. Add these lines to that file


return array(
   'friend:add' => 'Make a new friend',

Make sure that you do not have any spaces or newlines before the <?php.

You’re done now and should be able to enable the plugin and see the change. If you are override the language of a plugin, make sure your plugin is loaded after the one you are trying to modify. The loading order is determined in the Tools Administration page of the admin section. As you find more things that you’d like to change, you can keep adding them to this plugin.

How do I find the code that does x?

The best way to find the code that does something that you would like to change is to use grep or a similar search tool. If you do not have grep as a part of your operating system, you will want to install a grep tool or use a text-editor/IDE that has good searching in files. Notepad++ is a good choice for Windows users. Eclipse with PHP and NetBeans are good choices for any platform.

String Example

Let’s say that you want to find where the Log In box code is located. A string from the Log In box that should be fairly unique is Remember me. Grep for that string. You will find that it is only used in the en.php file in the /languages directory. There it is used to define the Internationalization string user:persistent. Grep for that string now. You will find it in two places: the same en.php language file and in /views/default/forms/login.php. The latter defines the html code that makes up the Log In box.

Action Example

Let’s say that you want to find the code that is run when a user clicks on the Save button when arranging widgets on a profile page. View the Profile page for a test user. Use Firebug to drill down through the html of the page until you come to the action of the edit widgets form. You’ll see the url from the base is action/widgets/move.

Grep on widgets/move and two files are returned. One is the JavaScript code for the widgets : /js/lib/ui.widgets.js. The other one, /engine/lib/widgets.php, is where the action is registered using elgg_register_action('widgets/reorder'). You may not be familiar with that function in which case, you should look it up at the API reference. Do a search on the function and it returns the documentation on the function. This tells you that the action is in the default location since a file location was not specified. The default location for actions is /actions so you will find the file at /actions/widgets/move.php.

Debug mode

During the installation process you might have noticed a checkbox that controlled whether debug mode was turned on or off. This setting can also be changed on the Site Administration page. Debug mode writes a lot of extra data to your php log. For example, when running in this mode every query to the database is written to your logs. It may be useful for debugging a problem though it can produce an overwhelming amount of data that may not be related to the problem at all. You may want to experiment with this mode to understand what it does, but make sure you run Elgg in normal mode on a production server.


Because of the amount of data being logged, don’t enable this on a production server as it can fill up the log files really quick.

What goes into the log in debug mode?

  • All database queries

  • Database query profiling

  • Page generation time

  • Number of queries per page

  • List of plugin language files

  • Additional errors/warnings compared to normal mode (it’s very rare for these types of errors to be related to any problem that you might be having)

What does the data look like?

[07-Mar-2009 14:27:20] Query cache invalidated
[07-Mar-2009 14:27:20] ** GUID:1 loaded from DB
[07-Mar-2009 14:27:20] SELECT * from elggentities where guid=1 and ( (1 = 1)  and enabled='yes') results cached
[07-Mar-2009 14:27:20] SELECT guid from elggsites_entity where guid = 1 results cached
[07-Mar-2009 14:27:20] Query cache invalidated
[07-Mar-2009 14:27:20] ** GUID:1 loaded from DB
[07-Mar-2009 14:27:20] SELECT * from elggentities where guid=1 and ( (1 = 1)  and enabled='yes') results cached
[07-Mar-2009 14:27:20] ** GUID:1 loaded from DB
[07-Mar-2009 14:27:20] SELECT * from elggentities where guid=1 and ( (1 = 1)  and enabled='yes') results returned from cache
[07-Mar-2009 14:27:20] ** Sub part of GUID:1 loaded from DB
[07-Mar-2009 14:27:20] SELECT * from elggsites_entity where guid=1 results cached
[07-Mar-2009 14:27:20] Query cache invalidated
[07-Mar-2009 14:27:20] DEBUG: 2009-03-07 14:27:20 (MST): "Undefined index:  user" in file /var/www/elgg/engine/lib/elgglib.php (line 62)
[07-Mar-2009 14:27:20] DEBUG: 2009-03-07 14:27:20 (MST): "Undefined index:  pass" in file /var/www/elgg/engine/lib/elgglib.php (line 62)
[07-Mar-2009 14:27:20] ***************** DB PROFILING ********************
[07-Mar-2009 14:27:20] 1 times: 'SELECT * from elggentities where guid=1 and (  (access_id in (2) or (owner_guid = -1) or (access_id = 0 and owner_guid = -1)) and enabled='yes')'
[07-Mar-2009 14:27:20] 2 times: 'update elggmetadata set access_id = 2 where entity_guid = 1'
[07-Mar-2009 14:27:20] 1 times: 'UPDATE elggentities set owner_guid='0', access_id='2', container_guid='0', time_updated='1236461868' WHERE guid=1'
[07-Mar-2009 14:27:20] 1 times: 'SELECT guid from elggsites_entity where guid = 1'
[07-Mar-2009 14:27:20] 1 times: 'UPDATE elggsites_entity set name='3124/944', description='', url='http://example.org/' where guid=1'
[07-Mar-2009 14:27:20] 1 times: 'UPDATE elggusers_entity set prev_last_action = last_action, last_action = 1236461868 where guid = 2'
[07-Mar-2009 14:27:20] DB Queries for this page: 56
[07-Mar-2009 14:27:20] ***************************************************
[07-Mar-2009 14:27:20] Page /action/admin/site/update_basic generated in 0.36997294426 seconds

What events are triggered on every page load?

There are 4 Elgg events that are triggered on every page load:

  1. plugins_boot, system

  2. init, system

  3. ready, system

  4. shutdown, system

The first three are triggered in Elgg\Application::bootCore. shutdown, system is triggered in \Elgg\Application\ShutdownHandler after the response has been sent to the client. They are all documented.

There are other events triggered by Elgg occasionally (such as when a user logs in).

Copy a plugin

There are many questions asked about how to copy a plugin. Let’s say you want to copy the blog plugin in order to run one plugin called blog and another called poetry. This is not difficult but it does require a lot of work. You would need to

  • change the directory name

  • change the names of every function (having two functions causes PHP to crash)

  • change the name of every view (so as not to override the views on the original plugin)

  • change any data model subtypes

  • change the language file

  • change anything else that was specific to the original plugin


If you are trying to clone the groups plugin, you will have the additional difficulty that the group plugin does not set a subtype.