Gallery2:FAQ - Gallery Codex
Personal tools


From Gallery Codex


Getting Gallery2

How can I get Gallery2 on my webserver?

Copy the Gallery 2 files to a directory on your webserver. There are several alternatives for this step:

  • Ideally, you can use subversion to install and update your Gallery 2 installation directly on the server. But this option is only available if you have command line access to the server (ssh/telnet).
  • The next best alternative is to upload the gallery2.tar.gz or archive via FTP or another method. Then unarchive / extract the archive in the command line (ssh/telnet) or with a miniature PHP script with the command tar -xzf gallery2.tar.gz for the .tar.gz archive or unzip for the .zip archive. Some webhosting companies offer a control panel with a web file-browser which is capable of extracting / unarchiving archive files. It's worth a try to check if this option is available.
  • If you have neither of these options, you have to upload the complete contents of the Gallery 2 archive to the webserver with an FTP program. This will take a lot of time and is error-prone. In this case, pay special attention to the System Checks step of the installer and make sure that there are no missing or modified files.

Once I have G2, where do I begin?

The BEST place to start is /gallery2/README.html. If you wish to jump ahead and start the install, you can point your browser at /gallery2/install/ instead. If it's your first time, you will need to visit the README.html in order to find database setup instructions.

Does G2 have any special requirements?

Gallery 2 requires many of the same things that G1 required. A web server, php and some graphics manipulation programs. You probably already know these things... but there is ONE new requirement: a database. Right now, there is support for MySQL 3,4, PostgreSQL and Oracle 9/10. Of course, the other requirements are a web server (apache, iis, zeus?), php (4 or 5) and some graphics manipulation packages (netpbm, imagemagick, ffmpeg, gd). Space for the images is probably one of the more obvious requirements :)

I can't upload images or see thumbnails in my galleries using a Fedora Core 6 host.

The GaphicsMagick package on Fedore Core 6 on both x86 and x86_64 currently has a flaw in it where the thumbnail creation process causes a segmentation fault. There is a detailed bug logged to Fedora on this reference (BugID 237803). this FAQ will be updated once the Fedora team has evaluated and fixed this issue. This will also be tested on Fedora Core 7 and updated if appropriate.

How can I get the latest version of Gallery2?

You can download the latest official release of G2 from the sourceforge download page. Official packages usually released not more than two times in a year, thus they might miss the latest features and improvements.
There are two ways of keeping current any time, using nightly builds or using Subversion.
Chetan Sarva, Jesse Mullan and Gallery2.EU both offer nightly builds.
The instructions for using Subversion can be found here . You can also find instructions for using TortoiseSVN here .

To get the SVN version of Gallery, see the next FAQ item.

Should I use nightly builds or Subversion?

That is up to you, I would suggest Subversion if you are comfortable working with it or don't mind learning. Once you get the original source from Subversion, updating is as simple as going to your G2 directory and typing "svn update".

Subversion uses too much disk space!

Subversion keeps a second copy of every file so commands like "svn status" and "svn diff" can run quickly, without going over the network. This does double the space required.. if you like the convenience of "svn update" but aren't doing development so you don't use status/diff much, then vote for this feature and hopefully subversion will support it someday. For now we offer a script called svnSlim.

How to upgrade Gallery2?

See: Upgrading Gallery 2

How do I prevent users from accessing my site during maintenance or upgrades?

Gallery 2.1+ has a "Maintenance mode" feature. Edit your config.php file using a text editor and find this section. It has instructions for turning on this mode. Example settings (use only one of these lines):

 $gallery->setConfig('mode.maintenance', true);
 $gallery->setConfig('mode.maintenance', '/maintenance.html');
 $gallery->setConfig('mode.maintenance', '');

Site administrators may still use the application while the site is in maintenance mode.

Typical upgrade process:

  1. Turn on maintenance mode;
  2. Put new code in place;
  3. Browse site as admin and make sure everything looks OK;
  4. Activate or configure any new modules/themes/etc you wish to use;
  5. Turn off maintenance mode.

My upgrade failed, and now when I try to get into my site, all I get is "Site is temporarily down for maintenance"

If a upgrade did not complete successfully, there might be a line in your "versions.dat" file located in the base folder of your albums directory that says "maintenance-mode". If this is the case, remove the line, and connect to your site's main page where the upgrade will start from the beginning.

Development Specific

I really wish this feature were part of G2, is it planned?

It is possible that it is planned. See this list of requested features. Also see the feature request section on sourceforge . If you don't see your idea listed you can file a feature request on sourceforge and/or start a discussion about your idea in the G2 Development forum. If you do see your idea listed it may still be a long time before it gets implemented so if you or someone you know can help out with development, please do!

I would love to write some modules, got anything useful for me?

Start with G2 Developer Starter Kit . There you will find reference to how our team works and where to find the needed documentation. First link there is the G2 Developers Guide which is a must-read before you start. Not every detail is described there yet and some stuff is outdated, but there you will get the general "feeling" on how and why our architecture is how it is. The API for all classes is self-documented with phpdoc in the code, which is extracted to the G2 API Documentation (last link in the Starter Kit). If you are on Windows and have trouble with the Makefiles to generate stuff for you, have a look at virshu 's howto Building Gallery 2 on Windows.

How can I integrate G2 into my website?

For basic integration, you can edit the theme templates to show Gallery 2 inside your own page with your header / footer / menu etc. Please see Visual Integration HowTo as well as the Theme and Template docs.

For application level integration (embedded G2) see the Integration HowTo and the Embedding & Integration Forum for existing integrations and to discuss your plans and issues.

I have some experience in linux compiling and noticed some make files and other things that would appear to need compiling... do I need to?

The Makefiles are only needed by gallery2 module developers. If you are just using G2, you don't need to "make" anything. For developers, the Makefiles automate boring tasks such as:

1) generate compiled translation files (.mo) from source language files (.po), 
2) generate database schemas from entity definitions, 
3) generate interfaces to access members of entities. 

How can I "zap" my G2 data? How do I easily clear out /g2data and the DB?

If you have manually dropped your DB or some of the files are not deletable by you (for instance, they are owned by the webserver's user) you might find Bharat's Cleanup Script useful. You can also point your browser to /gallery2/lib/support/ or /gallery2/lib/test/tools, the former is for those with any package but the dev package. The latter is part of the dev package.

Also, the G2 installer can "clean" your g2data directory. That is, it removes everything and then it adds the basic structure again, just with empty subdirectories. For this, you have to make sure there is a versions.dat file in the g2data directory and then advance to the Database Setup Step (step 5) and after hitting save, you should see the option "Erase".

General Gallery2 FAQ

Does G2 work with PHP 5.3?

Gallery 2.3.1 has updates for PHP 5.3.x compatibility. This release should still be compatible with PHP 4 as well, but if you encounter any problems then try switching back to Gallery 2.3.

Does G2 work with Safe Mode PHP?

Gallery is NOT designed to work with safe mode. You can see the sticky thread in the G2 development forum for an in depth discussion. Also see this topic and this topic for details of some experiments in getting G2 to work with safe mode.

What's PHP Safe Mode? From the official [PHP Safe Mode documentation]: "The PHP safe mode is an attempt to solve the shared-server security problem. It is architecturally incorrect to try to solve this problem at the PHP level, but since the alternatives at the web server and OS levels aren't very realistic, many people, especially ISP's, use safe mode for now."
If you don't know what PHP is or how to turn Safe Mode off, you are probably not the person in charge of the webserver where you want to host a Gallery. Please contact your webhost / server administrator to resolve the problem.

Why can't I upload big files (over a megabyte or two)?

The upload limits are enforced by the PHP / webserver configuration and not by Gallery 2/3.

In short: The administrator can change the upload_max_filesize and post_max_size directives in php.ini (the PHP configuration file). Also, you can try to override the system-wide default settings in a .htaccess file. Example, add this to your .htaccess file in your gallery/ folder to set a upload limit of 10 MegaBytes:

 php_value post_max_size 10M
 php_value upload_max_filesize 10M

This can result in a "Internal Server Error" (error status 500) on all your Gallery pages. If you get an error after this change, remove your changes. That means that your webhost doesn't allow such changes in .htaccess.

An alternative that works for some users: Add a php.ini file in your gallery/ folder with the following contents (notice the difference, here we have a = and no php_value):

 post_max_size = 12M
 upload_max_filesize = 12M

This may or may not work. You can check if these changes have actually changed your limits by browsing to your add items -> from browser page.

Changing to bigger value "memory_limit =" might also help. Note though that the memory_limit does not have to be exceed the file size of the files that are uploaded. memory_limit plays a bigger role when using GD as your image toolkit module. More on that topic can be found in other FAQ entries.

If you're using Apache 2, especially with something like RedHat, you may need to edit another directive, LimitRequestBody, as described in this forum post. Setting this directive to 0 (i.e. LimitRequestBody 0) will allow you to upload as big a file as you want (until you hit upload_max_filesize and/or post_max_size -- see the above email link for more information).

Dreamhost customers (and perhaps customers of other providers) should try searching for specific instructions on how to accomplish this. In the case of Dreamhost, they provide a wiki page describing exactly how to accomplish it here. I have personally tested it and it works. It boils down to creating a cgi-bin directory, copying their cgi php handler and setting it to be your default php handler. They also provide information on how to create a script that keeps php.ini and php.cgi up to date, but with your settings instead of theirs.

The default Apache configuration on Debian Lenny: put something like this into your Apache configuration if you are using G3:

    <Directory /var/www/gallery3/>
    AllowOverride All

Another option is to ftp to a folder on the local server and use the "Add Item" -> "From Local Server" option. You may need to rebuild the thumbnail for that item. This works on the 1and1 servers.

PHP memory_limit - Why do I get the error Allowed memory size of Xxx bytes exhausted?

You are exhausting the available memory that PHP has access to. In php.ini there is a config variable named memory_limit that by default is set to 8MB. Edit php.ini and increase it to a larger value (restart Apache afterwards). If you don't have access to php.ini, you can add this line to your .htaccess file in your gallery2 folder. Usually, unless you are the owner of the server, you don't have access to change php.ini. If there is no .htaccess file yet, you can create one (it's just a text file with the name '.htaccess').

php_value memory_limit [new memory limit]

To change it to 24 MB, write:

php_value memory_limit 24M

If the .htaccess method does not work or if you get an internal server error after adding this line, remove the line from the .htaccess again. You can also try to change the memory_limit by adding the following line right after '<?php ' in install/index.php and in main.php:


If there's no "memory_limit" parameter in your phpinfo page, then all PHP/Webserver processes are limited by the per process max memory limit. You'll have to ask an administrator to change the limit in this case. On linux/unix, you can check the limit with the following command in the shell:

ulimit -a

Or with PHP with a script check.php

<?php print system('ulimit -a'); ?>

Does gallery remote work with G2?

It would appear it does, point gallery remote at the base url of your gallery. For instance, I would point it to ""

Note: Gallery Remote doesn't work with Gallery 2.2.1 - nor does iPhotoToGallery... yet

Can I update from G1 -> G2?

Yes. The basic strategy is that you install and configure a copy of Gallery 2 right next to your copy of Gallery 1, then you use the migration module to import all your Gallery 1 data (users, albums, photos, metadata) into your Gallery 2. This will make a complete copy of your data in Gallery 2 and then you're free to delete your Gallery 1 install. It will even give you mod_rewrite rules that can redirect all your old Gallery 1 urls to the correct places in Gallery 2. If you don't have enough free disk space to migrate it all at once, you can migrate a few albums at a time.

Please refer to the detailed migration guide if you have any problems.

Where can I find NetPBM, jhead or ImageMagick binaries to use with G2?

You can find links to NetPBM and jhead on the Gallery Download Page. You might also find Image Magick binaries here. The ImageMagick binaries are installed on /usr/bin which is the default when you configure Gallery after the one-click install.

Where can I find unzip / zip binaries to use with the zip cart module?

You can find them here , but keep in mind this is a 3rd party site not under Gallery's control.

I customized a *.tpl file, but then removed it... but the customization is still showing up. Did I do something wrong?

If you remove a local/*.tpl file it won't switch back to the *.tpl file due to smarty caching. You can get it to switch back to *.tpl by clearing the smarty cache manually on the filesystem, running the Flush Templates task in Site Admin/Maintenance, using Cache Maintenance found in the /lib/support/ page or by doing 'touch filename.tpl' which causes the last change time to update.

How can I move my storage folder to another path?

Here's a step by step guide:

  1. Before moving the directory, consider the security aspects and ensure that the new home for your Gallery data folder is outside the web-root.
  2. Move the storage folder e.g. by using the move/rename feature of your ftp application, or a file browser in your webhost's admin panel or within the shell.
  3. Verify that permissions on the directory and files inside are owned by the web server or writable (chmod 777)
  4. Edit config.php manually. Update the line:
$gallery->setConfig('', 'some/path'); 
(Replace 'some/path' with the correct value.)

Save config.php, and you're done.

To save time, you don't need to move everything in the storage folder. Specifically you can leave behind the contents of the cache folder *except* the cache/derivative folder, which you do want. Everything else in the cache folder will be recreated by Gallery as needed.

How can I move my Gallery installation from one folder to another?

Here's a step by step guide:

  1. Deactivate and uninstall the url rewrite module if it's active (not just disable the rewrite rules, disable and uninstall the whole module in site admin -> modules (plugins in later versions)).
  2. Move the gallery folder (move/rename it with an FTP application, a file browser or with a shell). If you choose to move it from a subdirectory to the root of your website, just move all files and directories that are in the gallery folder to the web root directory.
  3. Edit config.php manually. If the g2data was within the gallery directory and you moved it, update the line:
$gallery->setConfig('', 'some/path'); 

If you use a multisite install, you also have to update:

$gallery->setConfig('galleryBaseUrl', );

Save config.php, and you're done.

If you are using a PHP accelerator (see List of PHP accelerators), you may need to clear its cache before the new settings take effect. Old installation paths may still be present until they are cleared.

How can I move my Gallery installation from one server to another?

Here is a step by step guide:

  1. Prepare the old server
    1. Put Gallery2 on the old server into maintenance mode
    2. Upgrade Gallery 2 on the old server to the latest version. Download Links. Note that if the version on the old server is earlier than v2.2.6, you might want to upgrade to v2.2.6 first before moving to the latest version. [Get v2.2.6 files]
    3. Navigate to "YOUR_GALLERY/lib/support/index.php?cache" and clear the cache.
    4. You may delete the g2data/locks directory if you want
    5. DO NOT use a package manager (yum, apt-get etc) or a "one-click" installer for the upgrade!!
    6. Deactivate AND uninstall the url rewrite module if it is active.
  2. Backup your installation
    1. Zip up and download your g2data folder to your local machine.
    2. Zip up and download the Gallery 2 folder to your local machine.
    3. Export your database. See Howtos
  3. Prepare the new server
    1. Create a folder for Gallery2
    2. Copy the old g2data folder to an equivalent location on the new server as it was on the old server.
    3. Create a database on the new server with the same name and login details as it was on the old server.
    4. Use the database manager on the new server to import the Gallery 2 database file.
      1. If you're using MySQL and moving from a Windows based server to a *nix (unix, linux, ...) based server, you have to change each database table name from lower case (e.g. g2_albumitem) to a case-sensitive name (e.g. g2_AlbumItem). See script to automate this process a bit.
  4. Use your ftp client to upload the "Minimal" version of Gallery 2 to the new server.
    1. Use the "downloads" link on the top right of this site to get a copy.
    2. DO NOT use a package manager (yum, apt-get etc) or a "one-click" installer for the installation!!
    3. Make sure it is the same version as you have on the old server
  5. Use your ftp client to change the owner of the g2data dir recursively (all files and folders) to the server's PHP user for your account.
    1. Your webhost should be able to do this for you if you do not know the account's php user.
    2. Alternatively, you can make sure that all process users on the server can read, write and delete files in this directory (chmod 777). Again, your webhost should be able to help if required but the first option is better.
  6. Copy needed files from the old installation to the new server
    1. Copy any modules you have in "modules" folder from within the old Gallery 2 folder you downloaded to your local machine earlier that are not already in the "modules" folder on the new server to that folder. Make sure you do not overwrite any existing modules on the new server.
    2. Copy any themes you have in "themes" folder from within the old Gallery 2 folder you downloaded to your local machine earlier that are not already in the "themes" folder on the new server to that folder. Make sure you do not overwrite any existing themes on the new server.
    3. Copy any "/themes/Theme_Name/local" folders you may have on the old Gallery 2 folder to the equivalent location on the new server if not covered by the step above.
  7. Browse to the new installation with your web browser and follow the on screen installation instructions.
    1. On the database setup step, enter the database details from your old config.php file
    2. Point the installer in the storage setup step to the g2data folder (which is now not empty).
  8. Go to G2 Site Admin and update/reactivate plugins if needed.
    1. All modules that depend on external programs may need to be tested and reconfigured.
    2. Also make sure that the mail function works on the new server.
  9. Switch off the maintenance mode

How can I export data from one G2 installation and import it to another?

Unfortunately, there's no tool to export/import data from one G2 installation (source) to another (target). But there are a few methods that may solve your problem.

  • If there's no G2 installation yet on the target server, just copy your existing G2 installation to the target server. See the FAQ entry about moving a G2 installation from one server to another.
  • If the target G2 installation is empty or doesn't have much data yet, we'd recommend removing the target G2 installation completely, then copying the source G2 installation to the target server and then add your previous albums again, manually or with the recursive "From Local Server" method.
  • If both G2 installations are already populated with a lot of data, you can import albums/photos files only. Descriptions, keywords, user data, ... are lost, but it imports all albums with all items in the correct structure. You can also decide to only import selected albums and you can specify the target parent album: Copy the g2data/albums/ directory of the source G2 installtion to a directory somewhere on the server of the target G2 (but not into the g2data/ directory). In your target G2, go to "Site Admin" -> "Web/Server" and add the directory /path/to/source/g2data/albums/ as a local server upload path. Of course your path is different from this example path. Then go to back to the top album of your target G2 and click "add item" -> "From Local Server" and select the path you just entered in site admin. Select the albums you'd like to import and start the process. It will add all albums / photos recursively, that is, it adds them including all sub-albums etc. Once the process is finished, you can remove the /path/to/source/g2data.albums/ folder from the target server.

Why does the random image or random highlight not obey permissions? How come some of my images in private albums are shown?

Permissions are handled on an item by item basis, not an album by album basis. Just because "album01" is private, doesn't mean that "album01/album02/image3" is also private. This is by design and intentional, BUT the problem is in the interface which does not mention or explain this in any way. Someday the permissions UI will be improved.

I use NFS and Gallery isn't working, is there a solution?

By default Gallery 2 uses flock for locking and this is known not to work over NFS. Go to Site Admin / General and switch to database locking instead.

Is it my imagination, or is G2 slower than G1?

You're probably not imagining it. There are three main areas where Gallery 2 is going to be slower. Gallery 2 uses a database for its storage. This means that even the most trivial operations require communication with the database to get answers. In comparison, Gallery 1 stores everything in fairly small flat files and it loads all the data into memory and then operates on it. For small Gallery installations on hardware that is 3+ years old, you're going to find that Gallery 1 runs a fair bit faster. However, Gallery 1 will not scale as effectively so as you start to get up to having 5-10K photos, you'll find that Gallery 2 is much more efficient. Having a database also allows other applications to interact with Gallery data, which is a big advantage over Gallery 1's proprietary data format.

Gallery 2 provides complete image security. If you restrict a photo based on its permissions, no outsider can get to it. This is in contrast to Gallery 1 that merely creates urls to images that an outsider could browse to, if he or she knew the url. However, this security comes at a performance cost. We are considering different approaches, including the possibility of allowing you to lower or remove this security threshold to increase your performance.

G2 is a much larger framework than G1. It's designed to be incredibly flexible and maintainable. This leads to having a lot more code and because of the nature of PHP, this causes pages to load a little slower. However, this also means that PHP accelerators like (see List of PHP accelerators) can effect very substantial performance increases when properly used in conjunction with G2. We recommend this option, if it's available to you (i.e. if you have full control over the PHP installation on your server).

Performance is an important factor to us. We have introduced caches at strategic places and are working on ways to improve all of the issues above to increase performance. It is secondary to making a fully-featured product for now, but as we get closer to the official release date it will gain higher priority for the development team.

For further tips, be sure to check out Gallery 2 Performance Tips.

Note: There's a known bug in the 2.0 release where if you import a large number of albums from Gallery 1, it can fail to optimize the permissions table leading to really bad performance (2-3+ second response times for a page load). If that happens, you can fix it. Just change any permission anywhere in your G2. You may have to do this a couple of times because each time you change a permission it has a 50% chance of re-optimizing your permission table. If you want to check the before/after, you can run this query

  select count(*) from g2_AccessMap;

Before and after the permission change. If the number of rows drops dramatically (like from 2000 rows down to 30) then you've fixed the problem.

When I upload an image, G2 doesn't seem to create sized images or thumbnails... also, when I enter an album for the first time it takes a LONG time to load. What is the deal, yo?

G2 has some fundamental differences from G1. In G1, thumbs and sized images were created at image upload. In G2, these items are not created UNTIL they are accessed/needed. This means that the first time you view a sized image or album, it may take a while for the images to be generated. Of course, subsequent visits should be much faster because they already exist. I believe there are also plans for the ability to generate the needed images at upload or when ever the user wishes, independent of viewing them for the first time. Update: There is now a check box present during import and upload that allows for the generation of thumbs/sized images right then. Using this will increase the time it takes to upload/migrate, but will take care of it immediately instead of when a user first requests the image.

I am having trouble configuring a graphics toolkit (ImageMagick, NetPBM or ffmpeg). Help?

First- when the configuration asks for the path it is not asking for the path to the gallery2 module (like gallery2/modules/imagemagick). These directories are G2's interfaces to these programs and not the programs themselves. You need to find or install the binaries on your system, make sure they are executable, and enter the appropriate path in the configuration. See:
Using windows: set the permissions correctly;

Can I change the timezone for dates/times displayed in G2?

Add a line like this in config.php before the ?> at the end:


Replace PST8PDT with the appropriate timezone string. For more information about appropriate timezone strings, see this Wikipedia entry on Zoneinfo. For actual acceptable values, see this list on Wikipedia. On PHP 5.2 or higher the preferred method is a date.timezone setting in the php.ini file, or a line like this before the ?> at the end of your config.php file:


Can I rename main.php?

To use a different main php file after G2 is installed follow these steps:

  • Disable and uninstall the URL-rewrite module.
  • Copy or symlink main.php to the new filename.
    • If you want index.php just remove/delete index.php and rename main.php to index.php
  • Add a line like this in config.php before the ?> at the end:
define('GALLERY_MAIN_PHP', 'filename.php');

As of 2.0-rc-2 you can also do define('GALLERY_MAIN_PHP', ''); to set the default document to / hiding all reference to index.php or main.php. You'll also need to set baseUri, the now second-to-last line in config.php, to '/' (for example for a domain-level install of gallery).

Can I install if my server only allows .php4 extension for php files?

If your system does not accept ".php" as an extension for PHP files and requires ".php4" then follow these steps:

  1. Rename index.php, main.php, install/index.php and upgrade/index.php to end in php4 extension.
  2. Browse to install/index.php4 and proceed with the install. Note the "Go to Gallery" link at the end of the install will not work.
  3. After installation follow the steps in the FAQ entry above to change main.php to main.php4.
  4. Optionally rename config.php to config.php4 and update end of to reference config.php4 (to protect config.php contents from being viewable via browser).
  5. Now you should have a functioning G2.
  6. To support upgrades, find this line in upgrade/index.php4:
 function generateUrl($uri, $print=true) {

Just after that line add:

 $uri = str_replace('index.php', 'index.php4', $uri);

And change upgrade/index.php to upgrade/index.php4 in main.php4.

Why don't you support PHP 5.0.3?

PHP 5.x versions older than 5.0.4 have a very important bug (bug id 32290). This bug affects object oriented software like G2, and the libraries that G2 uses (Smarty, ADOdb). We know of at least two features that don't work because of this bug (advanced search, publishxp). There may be many other problems, including data integrity issues.

Bottom line: PHP 5.0.3 has a grave bug. Gallery cannot reasonably work around it. Upgrading to PHP 5.0.4+ should resolve it.

If you must stick with PHP 5.0.3 you can remove the PHP version check that prevents you from installing G2 by changing a few code lines in install/steps/SystemChecksStep.class and upgrade/steps/SystemChecksStep.class. You can also fix the advanced search and publishxp, it's described in this forum topic.

How do I backup G2?

A full backup consists of your 'g2data' directory, database, /gallery/config.php and /gallery/.htaccess. NOTE: If you don't use the URL Rewrite module you won't have a .htaccess file.

My Gallery URLs begin with /v/ and /d/, why?

Gallery needs these prefixes (/v/, /d/, ...) to detect different types of requests. /v/ for album and photo "view" pages, /d/ for download URLs, etc. You can change this prefix in Site Admin -> URL Rewrite. You can even remove the prefix for the view pages (/v/). However, you should be aware that if you remove the /v/ prefix, you may no longer have top level albums which have the same name as one of the directories in the Gallery directory. In other words, creating a top level album "lib", "themes", "modules", "install", .. is ok when you have a /v/ prefix, but it will result in problems when removing this prefix. There's a maintenance task to check that there's no conflict like this in your Gallery (Site Admin -> Maintenance).

How can I use Gallery 2 Images in other Websites?

You would like to show your Gallery 2 images in another website or forum (bulletin board) or you would like to add a link on another website to a specific image / album of your Gallery 2.

  • For image links, right-click with your mouse on the image in Gallery 2 and copy the image address (most browsers offer this feature)
  • For links to a specific album / item in your Gallery 2, browse to the album / item and copy the address that is in the address bar of your browser (remove the g2_GALLERYSID= stuff, if there is any)
  • If you are wondering why the links look like main.php?g2_view=core.ShowItem&g2_itemId=35 for item links and main.php?g2_view=core.DownloadItem&g2_itemId=35 for image links: These links may look a little weird, especially the DownloadItem link since you'd expect that a image URL looks rather like album/image.jpg, but it is actually a image link. If you want nicer links that look more normal, e.g. image links that end with .jpg, then activate the Gallery 2 URL rewrite module. You can do that by logging into Gallery2 with the administrator account, then click site admin, then Plugins. At the top of the list you should see URL Rewrite, and on the right of that line, click on activate. Follow the on-line instructions from there. When you're successful, a green tick appears next to the plugin name.
  • There is a module that prepares image and item links for you such that you don't have to right-click etc. See: Preformatted URLs Module

How do I get updated items to show first in an album (like new items do)

Troubleshooting Gallery

I have a problem with something, what should I do?

To start with, updating to the latest code is a good idea. It is possible that it is already fixed. Next you should probably look around the forums to see if the problem has already been posted. Try your luck with the search function in the forums. If that doesn't help, you probably want to ask for help in the support forum. Include as much information as possible in your support request.

What information is required when I ask for help in the forums?

When you create a new topic in the support forum, please include the following information:

  • G2/system information: Copy'n'paste your G2 system information from "Site Admin -> Maintenance -> System information" (you have to click "run now" to get the system information).
  • Please add a link to your website / G2 installation in the forum topic.
  • A phpinfo link is also very often needed. To create a phpinfo page on your server, do the following:
1. On your desktop, create a new text file
2. Open the text file and copy'n'paste the following:
 <?php phpinfo(); ?>
3. Save the text file and rename it to phpinfo.php (or any other file with the extension .php)
4. Upload the file to your gallery2 directory on the server
  • Make sure your file integrity is intact (see instructions)
  • A description of the problem (and the steps to reproduce if it may be a bug)
  • The relevant error message and debug output.
  • For problems in the installer the debug output should be displayed.. post the error message at the top and look for the error near the bottom of the debug output.
  • For errors while using G2 you'll need to turn on buffered debug output in config.php and then look near the bottom of the output for your error message. If you're unsure where the error message is you may post a link to the entire debug output, but please don't post the entire thing.

Getting the error message from debug output is particularly important for ERROR_STORAGE_FAILURE errors, as this is the only way to get the detailed error message from the database.

  • You can activate G2's debug mode in config.php (instructions are in config.php, you have to change the $gallery->setDebug(false); line).

The more information you provide, the more likely we can help you and the faster the issue can be resolved.

How can I make sure that my installation files are all intact?

Browse to or and advance to the System checks step. Make sure there are no warnings, and especially that the file integrity check passes (no missing / modified files). If there are missing / modified files, read this FAQ entry to fix it.

Even if Gallery has already been installed, you can access the upgrade/ or install/ wizard at any time. Just advance to the "System Checks Step" and don't go any further. This step will show a warning for missing or modified files in the "integrity check". If there is a problem, you can click on the "+" sign to see a complete list of affected files.

Thumbnails / resized images don't get generated properly, how can it be fixed?

Either you don't get any thumbnails / resized images at all or you get a "broken image" placeholder.

  • If you don't have any thumbnails / resized images at all, it means that there's probably no image toolkit module active in your G2 installation. G2 needs either the imagemagick, netpbm or GD module to be active to generate thumbnails and resized images.
    • Please read: Installing an Image Processing Library
    • Note: Imagemagick and netpbm both need an external binary application in addition to the G2 module. If the corresponding G2 module does not autodetect the path to your imagemagick / netpbm binaries, then it's most probably not available on your server. See the above link on how to get the binaries.
    • Note: GD is either available in your PHP installation or not. If it works, make sure you have a large PHP memory_limit (> 16 MB), since GD is the only image toolkit in G2 that uses the PHP memory and not system memory. You will get broken thumbnails / resized images with GD unless the PHP memory_limit is large enough.
    • Why does GD cause my PHP script to run out of memory?
      • Most often, the problem is that the memory_limit parameter in php.ini is set to something very conservative, like 8M (eight megabytes). Increase that setting and restart the web server. Of course, opening truly huge images can cause real memory problems, if several are open at once. 8,000 pixels times 8,000 pixels times four bytes for truecolor equals a walloping 256 megabytes.
      • Another real world example: Say you have an image that is 2576 X 1932
        • That is only a 1.4 Meg image compressed (jpeg)
        • Uncompressed: 2576 X 1932 X 4 = ~20Megs!
  • If you get broken thumbnails and resized images (e.g. 92x92 pixel resizes), it means image toolkit(s) are active in G2 but they fail to generate thumbnails / resized images successfully.
    • Sometimes the image toolkit modules of Gallery need to be reconfigured (e.g. if your webhost changes something or if you move servers). Uninstall the image toolkit modules (imagemagick, netpbm, gd, ffmeg, jpegtran, dcraw, ...) and then install them again and try to activate them again. Note: Deactivating is not enough. You need to uninstall these modules.
    • If you're using GD, then you probably need to increase the PHP memory_limit . The best sign that the memory_limit is the problem is if you get normal thumbnails for small images but broken / no thumbnails for large images (large in dimensions / filesize).
    • Most often if that happens, one or more image toolkits don't work correctly on your system. Try installing another image tookit module for G2, another toolkit might work.
    • If you have multiple image toolkits installed, try disabling all but one of the image toolkit modules. Then add a new image to G2 to check if it works now. If not, deactive this image toolkit and activate another one. Check again, etc.
    • You can also try to just change the image site admin -> toolkit priority, which is available if more than one image toolkits are active.
    • If activated, try to disable the Square Thumbnails module.
    • If activated, try to disable the EXIF module.
    • There may be a bug in PHP. Try adding $gallery->setConfig('apacheSetenvBroken', 1); to your config.php to disable using the apache_setenv() function
    • If everything fails: For netpbm and imagemagick, you can find out why it fails by looking at the debug output. Enable buffered debug mode and add a new item to G2 and look for "executing"..."Regular output:"..."Error output:"... in the debug output.
  • Once it works again, you can generate and fix the broken thumbnails / resized images with site admin -> maintenance -> Build all thumbnails/resizes
  • URL, "www" problem: If Gallery2 works OK when you navigate to (YourDomain.Ext) but fails with all broken images when you navigate to (www.YourDomain.Ext) Then see: [This FAQ] This seems to be host-dependent.
  • If you just went through an upgrade from a previous version and you didn't overwrite the existing code (you just copied over the database), you may have a Graphics Toolkit (such as mplayer) that isn't properly removed. I had to remove mplayer from the database manually by running the following query (I'm purposely being vague because you need to know what you are doing if you're going to try this): delete from g2_FactoryMap where g_implId = "mplayer";

Thumbnails / resized images don't appear but if i use www in front of my url it works. Full sized images are fine. How to fix?

  • I suspect that your one click install did not do the install properly. This is common with Fantastico one click installs.
  • Install and configure the URLrewite module. select mod_rewrite (Apache).
  • Once that is selected activate the module.
  • Navigate to the Site Admin -> Url Rewrite -> Setup tab.
    • There should be a grayed out box that has your url ( either or )
    • add your other url. ( either or )
  • Save

I need to use two different hostnames for the same server running Gallery, but with one of them all the page links are wrong. How do I fix it?

G2 constructs links to other G2 pages using the baseUri parameter in the config.php (you'll find it at the end of the file). If you set this parameter to blank ("") then all links in a page are built with the same hostname as the request was made to. So you can use two different names and the pages served for both will remain consistent.

I changed the language but nothing happens, what's wrong?

G2 depends on the system it runs on to switch to other languages than English. G2 needs php with gettext support and each language you want to switch to in G2 needs to be installed on your system. If you have command line access (ssh / telnet) to the (unix, linux) server, you can query for supported languages by `locale -a`. If only "C/POSIX" is returned, no other languages are supported and you need to reconfigure the locales and then restart apache.

Also try several variants of locales corresponding to your language. For example, fr_FR.iso885915@euro seems not to be supported by G2 while fr_FR.iso88591 works fine. Also, if you have a language variant installed (ex fr_CA), make sure you also have the "main" language (ie fr_FR) installed on your system.

Also, there is a bug if you use Gallery2 with Drupal 4.6.x using the gallery.module module Look here for this issue (fixed in 4.7.x integration).

Why can't I install with MySQL 4.1 or higher?

If the installer gives you an error like "Client does not support authentication protocol" then the MySQL support builtin to your PHP is using an older password scheme than your MySQL database. See here for more information and a workaround to get you up and running without having to recompile or upgrade your PHP.

I get an error about "max key length" installing with MySQL?

If you see this error while installing the Core module:

Specified key was too long; max key length is 1000 bytes 

then you need to switch the database character set to something other than utf8. Currently some indexes we use exceed this default MySQL limit if the charset is utf8.

I seem to be running into some sort of MySQL query limit, is there anything that can be done?

Some hosts setup a query limit on your MySQL database. This is usually a per hour limit and would be restored in time. Floridave believes that a reasonable value for this would be 50-70k, but some hosts might set it as low as 10k. See if your host will bump it up a little bit perhaps. A workaround is to create several users of the database and randomly use those users to connect:

I get only a blank screen when trying to view my Gallery, what's wrong?

A totally blank screen usually means that a php error has occurred. In normal operation all error messages are deliberately hidden, as a security feature to avoid revealing information about your website to a potentially hostile user who comes across the error. In order to reveal any messages you should follow the instructions below about how to display errors, and repeat the actions that cause the error. Having enabled error-reporting it is the report of errors now displayed instead of the blank page that is most likely to shed light on the problem; the often very long debug log shown with the page before the problem occurs is much less likely to be useful. Bear this in mind when asking for help in the Gallery Forums.

You can also look in your webserver's error logs for entries contemporaneous with the blank page being displayed. (contact your hosting provider if you're unsure how to do that.)

There are also generic things to check too: your PHP memory limit and other PHP configuration parameters. In most cases, G2 requires a memory limit of at least 16 MB, if you are using GD, it may require even a higher limit.

Please see:

When I click on item thumbnails, nothing happens, what's wrong?

Probably your PHP memory limit is too low. Increase your PHP memory limit to at least 16 MB. If the problem persists, you should activate immedate debug mode in config.php and report the problem in the forums.

Why do I see stray NetPBM and cmd.exe processes that never go away on my windows server?

If NetPBM is given a file that it can't support, it may try to put up a dialog box telling you about the error before continuing. Since your server can't display those error boxes, the rest of the image processing operations wait for you to click an "OK" button that you can't see. This may also result in G2 hanging for 30 seconds since it is waiting for the image processing to complete also. ImageMagick does not appear to have this problem.

What about the warning for missing & modified files in the installer & upgrader?

If there is a warning for missing or modified files in the installer or upgrader, you should take it seriously. Neither the install or upgrade process nor G2 as an application can work correctly with missing or modified files. Upload the modified / missing files again to your server until the warnings disappear. Possible reasons for missing / modified files:

  • Error during the FTP upload of the Gallery 2 files
  • Use of Winzip or other problematic archive programs to unarchive the Gallery 2 .zip.
  • There are reported issues for several unarchive programs on OSX

If you are a svn user, a warning for a few missing or modified files in the installer / upgrader systemcheck step is the norm. But if you experience any problems, this is surely one of the first places you should look into.

I get lots of "Warning: exec(): Unable to fork [cmd /c ...]" at the module's step in the installer for G2 (on the ImageMagick module) under Windows/IIS. Now what?

You need to give permissions for IIS to be able to read and execute the command interpreter ("cmd.exe"). Without it, Gallery won't be able to call external executables (like ImageMagick). Required steps:

1. Open a cmd-prompt with "Start", "Execute", then type "cmd.exe". Hit ENTER. 
2. At the prompt, type: 

This adds the "read" permission to the IIS-user for the cmd.exe. Close the prompt and then try activating the imagemagick module again. More Info

I use apache's mod_layout and notice some odd error messages, what is the problem?

If you use mod_layout with Apache, make sure it is disabled for gallery files. Gallery sometimes sends binary data back from a php file, so adding a header or footer to these requests will corrupt the data! Adding the following lines to your apache config file or your .htaccess should fix it.

# Disable layout header and footer for Gallery2 
LayoutIgnoreHeaderURI /path/to/gallery2/*.* 
LayoutIgnoreFooterURI /path/to/gallery2/*.* 
# PHP Gallery2 overide Layout 
<Directory /path/to/gallery2/> 

How to set/use Gallery in debug mode?

Edit your config.php and turn on buffered debug mode by changing this line:




Then try again. This time, you'll get quite a lot of debug output when you get the error. Look towards the bottom of the debug output and scan backwards for anything that looks like an error, then report that in the support forums. Usually that will give us enough information to work with. If you can't understand what you're seeing, err on the side of posting more info. If it's going to be more than 30-40 lines of output, you should save it into a text file and publish it on your own website and post a link to it here (so that the forum remains readable).

Where I should see dates I see "Wrong charset, cannot convert" or "Illegal character encoding" or "Illegal recode request".. what is wrong?

Some operating systems report invalid character sets to PHP leading to errors when trying to convert system-generated content (like day/month names in dates) to UTF-8. Work around this problem by placing the following in config.php:

$gallery->setConfig('systemCharset', 'ISO-8859-1'); 

Replace 'ISO-8859-1' with the appropriate character set for your system (other popular charsets include 'UTF-8').

An invalid locales config normally causes uploads to fail, with the Upload Applet error message Upload error: Upload failed: ". after each uploaded item and the From Web Browser just uploads one item with the status message Successfully added 1 file.

Note: For Gallery versions before Gallery 2.1, use the following instead of $gallery->setConfig():
require_once(dirname(__FILE__) . '/modules/core/classes/GalleryCapabilities.class'); 
GalleryCapabilities::set('systemCharset', 'ISO-8859-1');

I can't install G2, what should I do?

So you tried to install G2 but you get an error, probably in the install core module step. See the list of frequent installation errors.

I get a blank page / a network/webserver error, what's wrong?

If you are using PHP 5.0.3 or earlier PHP 5 versions, this is probably because of a bug. Therefore, these PHP 5 versions are not supported by G2. Either change to PHP 4.1+ or to PHP 5.0.4+.

This bug should occur in advanced search, in the publishxp module and in other places of G2.

I can't login anymore, what can I do now?

"Your login information is incorrect. Please try again."

If you see this error message, either the username or the password that you've entered is incorrect.

  • If you don't remember your password, please use follow the "forgot password" link on the login page.
  • If you forgot your username please contact the admin such that the admin can look up your username in the database.

"Logins to this account are temporarily disabled due to multiple failed login attempts."...

Does it say your user account is "disabled"? (since G2.2)

  • Use the "Forgot Password" link on the login page to reactivate your account.
  • If the server's email system isn't working, please contact an administrator. Admins can use "login.txt" instead and fix email or reset the user account. See -> "Reset User Password" (since Gallery 2.3) which points to

"You must enter the letters appearing in the picture."

If you see this error message, then you either ignored the CAPTCHA image or you CAPTCHA is enabled but no image is shown.

  • Please enter the letters and numbers from the CAPTCHA image into the input field below and try to login again.
  • If no CAPTCHA image (= image with letters) is shown, then CAPTCHA isn't working correctly and you need to deactivate it manually.

"Incorrect letters."

This error message is shown if you didn't interpret the CAPTCHA image correctly.

  • Please enter the letters and numbers from the CAPTCHA image into the input field below and try to login again.

How to manually login

Are you able to login manually? You can try to login manually with[formName]=UserLogin&g2_form[action][login]=Login&g2_form[username]=admin&g2_form[password]=secret (replace "secret" with your own password).

Copy and paste the stuff in bold. Don't forget to change secret to your password. If you've also changed the admin username from admin you'll need to change that as well.

Other Login Issues

  • If you've upgraded from a version older than beta 4, please read the README.html. By clearing the cookie cache of your browser, it should be fixed.
  • If you just have changed the cookie path / domain settings in the site admin options, first delete the GALLERYSID cookie in your browser. If that doesn't fix it, or if you can login again but it shows the GALLERYSID parameter in all URLs even if you browse around in G2, you most probably entered wrong values for the cookie path/domain. If you can't login anymore, deactivate cookies in your browser and login in G2. Go to site admin and fix the cookie path/domain values.
  • If you're using a version older than Gallery 2.0 RC-1 and G2 is running on a IIS webserver older than IIS-6, upgrade to G2 to Gallery 2.0 RC-1 or later. We had to fix an IIS-5 bug with a workaround in Gallery because MS was unable to fix it in the webserver.

Progress bars don't work, what's wrong?

If you have this problem it may be difficult to tell unless you are familiar enough with G2 to know where to expect progress bars to appear. Examples are upgrader and G1 migrate.. if you don't see a progress bar at all or it just flickers quickly on the screen when the request has completed then PHP's output_buffering mode may be enabled. Check php.ini and make sure output_buffering is set to off and no output_handler is configured.

If you are running Apache it can be configured with the deflate or gzip module and this will buffer all the output also. You can check by going to and putting in your gallery url and it will tell you if the deflate or gzip module is being used.

I get invalid urls with Roxen webserver, what's wrong?

You can try this patch.

I can't access G2 from my vHost or subdomain, what's wrong?

Probably you use the G2's short URLs which are generated by G2's URL rewrite module. If you have a .htaccess file in your gallery2 directory, this is the case. You have two choices:

  • Either access G2 only with one of the vHosts / (sub-)domains or
  • Don't use the URL rewrite module

And if you decide to use the URL rewrite module, you have to activate the module while accessing it from the correct / chosen vHost / (sub-)domain. To change it, access G2 from the URL which you used to install it. Deactivate and uninstall the URL rewrite module. Then access it from the URL that you prefer and install and activate the rewrite module again.

Technical background: When using the URL rewrite module, G2 has to store the path to the G2 main.php file in the database and in the .htaccess file. E.g. if the 'normal' URL is it stores '/gallery2' in the .htaccess file and in the database. If you then want to access it from a vHost that points directly to the gallery2 directory, e.g., then it would generate wrong redirects and URLs since G2 still assumes it is installed in a subdirectory '/gallery2' of this domain. You may notice that this doesn't apply to two different domains which have the same webroot.

I get "Notice: Only variable references should be returned by reference in ", what's wrong?

Most probably you are running PHP 4.4.0+ and use the PHP Zend Optimizer (see phpinfo). This is a Zend Optimizer bug. See for some explanations.

Solution: Use a newer Zend Optimizer version, e.g. ZendOptimizer-2.6.2 or later versions.

If you run PHP 4.4.0 but don't use the Zend Optimizer, then most probably you're using a G2 version which is older than G2 Beta 4. You should upgrade to the latest stable release of G 2.0.

If you or your host is unwilling to disable or upgrade the Zend Optimizer to a fixed version or change the PHP version, there's a workaround (solution discovered by Mark Scott, 13/10/2005, "I've found that removing optimization pass 1 removes the notices caused by optimizing away the variable that should be referenced and returned.") In php.ini replace:




You can also just suppress all PHP warnings but there's no guarantee that G2 actually works as expected:

/* in index.php, main.php and install/index.php */
error_reporting(E_ALL &~ (E_NOTICE | E_WARNING));

Related links:

MySQL "Client does not support authentication protocol" error

The reason for this is explained and several solutions are presented on this page: MySQL Reference Manual: A.2.3. Client does not support authentication protocol. Specifically, look for the instructions after:

Reset the password to pre-4.1 style for each user that needs to use a pre-4.1 client program. 
This can be done using the SET PASSWORD statement and the OLD_PASSWORD() function:
mysql> SET PASSWORD FOR 'some_user'@'some_host' = OLD_PASSWORD('newpwd');

Gallery Remote can't find my G2, what's wrong?

Possible reasons (GR = Gallery Remote, G2 = Gallery 2):

  • You need to activate the "remote" module in G2. See "Site admin" -> "Modules". If it isn't listed, download the module separately from the G2 Download Page. The module must be installed and activated
  • You used Gallery 1 before you switched to G2 and you still have the "gallery_remote2.php" file in your gallery2/ folder. Delete it.
  • You're using a proxy to connect to the internet. GR has problems with proxies.
  • Your G2 is embedded in another application and you use mode.embed.only = true in config.php. In G2.0.x, it works only mode.embed.only = false.
  • You have a very old version of GR. Download and install the latest stable release from the Gallery Download Page.
  • When you connect with your web browser to you get a nice-looking page that says the page is not found. See the [GR FAQ].

Publish XP shows a "web services error", what's wrong?

If this error shows up when trying to login to your G2 in the Publish XP wizard, then you probably have a problem with cookies in Internet Explorer. Delete the cookie cache in Internet Explorer and then start Publish XP again.

G2 doesn't accept the upload path that I define!

Two common "mistakes" when you don't have a dedicated -nix server.

  • If you're running G2 on a Windows machine, start the path with the drive letter (e.g. c:\ )
  • If you are on a shared host of a -nix machine, make sure that you give the full path of the directory on the server, not just the path of your share of the host. Check out this post for an example:

-nix server: When using a screen highlighting copy/paste action it's quite easy to inadvertently grab a preceding space (ie in front of the /home/). It can almost drive you to drink chasing apparently 'unaccepted' permissions...

Images don't show up and the album / photo links don't work, what can I do?

Possible reasons:

  • G2's URL rewrite module is active but doesn't work correctly. Fîx:
  1. Put G2 into maintenance mode
  2. Browse to

(replace with the URL of your own Gallery2 installation)

For versions before G2.2, use this URL instead:

If you get a Error (ERROR_PERMISSION_DENIED), then you're not logged in into your G2 and thus can't access the admin pages. In this case you have to login first and then use the above link. If the login view doesn't work, you can try to login manually with[formName]=UserLogin& g2_form[action][login]=Login&g2_form[username]=admin&g2_form[password]=secret (replace "secret" with your own password)

If you still get an error (ERROR_MISSING_OBJECT), go to Click the "Cache Maintainance" link, and clear all your db caches except for g2data/cache/derivative. Then, try the login link above, and finally, the deactivation link above that.

  • Your webserver is not properly configured and returns not the correct values for HTTP_HOST / HTTP_X_FORWARDED_SERVER

You can find out whether this is the case by looking at the page, look for the values of HTTP_HOST and HTTP_X_FORWARDED_SERVER. If HTTP_X_FORWARDED_SERVER is missing, that's fine. If HTTP_X_FORWARDED_SERVER or HTTP_HOST have another value than the real host name (the part after http:// of your G2 URLs), then this is a problem.

If you or your admin can't change the webserver configuration (hostname in httpd.conf for HTTP_HOST for apache webservers) such that it returns a correct value, you can hack modules/core/classes/GalleryUrlGenerator.class function getCurrentDomain() to return the correct value or to ignore HTTP_X_FORWARDED_SERVER, what ever you need.

How can I change the default theme when I can't reach site admin?

If you have more than one theme active and your current default theme doesn't allow you to access site admin -> themes to change the default theme (for whatever reason), then you can try to change the theme back to matrix, the official G2 theme, with the following URL:[action][saveDefaults]=1&g2_form[default][theme]=matrix

(replace with the URL of your own Gallery2 installation)

This will only work if you are already logged in as administrator. See another FAQ entry on how to manually login if the normal login method doesn't work anymore.

install/index.php is blank or shows an error. What's wrong?

This can have several reasons.

  • If the page is blank and you're using PHP 5.0.5, then you need to change the PHP version. See PHP bug 34635
  • If you get something like "Warning: session_start():"... then your PHP is misconfigured. You probably need to set session.save_path correctly (on linux / unix "session.save_path /tmp" is a good choice). And / or you need to configure the session.save_handler correctly ("session.save_handler files" is a good choice). These settings are in php.ini of your PHP installation and you need to restart the webserver after the changes. You may be able to set the necessary PHP session variables without altering your main php.ini file by placing configuration directives in your Gallery directory's .htaccess file (Reference).
  • Else: Make sure you run PHP 4.1.0 or a newer version and make sure PHP is actually used for .php files on the webserver.

I receive a database setup error using MySQL 5.x on Windows, what can I do?

If you're using MySQL 5.x on Windows and you can't get past the Database Setup Step in the installer and get a message like

The database privileges test did not complete successfully.
Failed to create a DB test sequence.Check the returned error message and README.html for missing privileges and clean up the database.

Then you most probably have a MySQL InnoDB Engine issue. To resolve it, try: Delete BOTH your MySQL DATA and LOG files at the same time and restart the server.

  • Step 1. Stop MySQL service
  • Step 2. Delete files (your paths may be different):
C:\Program Files\MySQL\MySQL Server 5.0\data\ib_logfile*
C:\MySQL Datafiles\ibdata*
  • Step 3: Restart MySQL service

If that doesn't work for you, change your default MySQL engine from "innodb" to "myisam" in your mysql configuration. Thanks to G2 users bzink5 and tippex for the solutions. The issue is dicussed in a forum topic.

The installer does not accept my login.txt, what's wrong?

There can be several possible reasons why you may not pass the authentication step of the installer:

  • Make sure you created / uploaded the login.txt file in your Gallery 2 folder on the webserver (the parent folder of the install/ folder) and nowhere else
  • Make sure this login.txt contains just the authentication key (a 1 line string)
  • If you can pass the authentication step but loop / fall back to step 1 after advancing to step 3 or higher, then you should use a nightly snapshot / release newer than 2005/11/17 since cookieless installing was broken for a short period before this date (inproper PHP session configuration values can also lead to cookieless browsing)
  • Make sure your PHP session.save_handler is set to "files" and not to "user" (or "mm"). In development builds since 2005/11/27 or since Gallery 2.1, you shouldn't have to worry about this setting (unless PHP ini_set / ini_get are disabled in your PHP installation). You can check these PHP configuration values in a phpinfo page on your server.
  • Try clearing your browser cookes. In some cases there might be conflicting cookies when several applications are installed on the same host and clearing the cookies ensure that Gallery gets a clean slate to work with during installation (This issue should be fixed in 2.2.1).

Movies are not playing in my Gallery, why?

I have changed the default theme and nothing works anymore. How can I switch back?

Use phpmyadmin / your mysql shell to execute the following query to change the default theme back to the matrix theme:

UPDATE g2_PluginParameterMap SET g_parameterValue = 'matrix'
WHERE g_pluginType = 'module' AND g_pluginId = 'core' AND g_parameterName = 'default.theme';

Afterwards, delete the db cache by browsing to, enter your password, click there on cache management and delete the db and template cache. Of course you need to replace with the actual address of your Gallery.

I get a warning for missing themes / modules in the upgrader, what should I do?

Probably you chose the wrong package for your upgrade. Only the full package has all official themes and modules. Another reason could be that you were using non-official / 3rd party modules / themes and you forgot to keep them in your modules/ or themes/ folder.

  • If the themes / modules that are missing are official ones, you can download them from the Download Page.
  • For 3rd party / non-official themes, please check the User Contributions page for the latest version of your modules / themes

If you can't get the latest version of a specific module / theme and nothing helps, the following SQL query can help you to get at least through the upgrade wizard:

delete from g2_PluginMap WHERE g_pluginId = 'PGtheme';

If a theme that is now unavailable was used as default theme or for one of your albums specifically, you will also have to update the g2_PluginParameterMap database table to change the default theme, e.g.

 UPDATE g2_PluginParameterMap SET g_parameterValue = 'matrix' where g_pluginId = 'core' and g_parameterName = 'default.theme';

And do the same for specicic albums (set the g_theme = NULL in the table g2_AlbumItem for those rows that have a theme that is no longer working in your G2.

If after removing incompatible modules you see errors when editing items in your Gallery like this:

in modules/core/classes/helpers/GalleryFactoryHelper_simple.class at line 208 (gallerycoreapi::error)
in modules/core/classes/helpers/GalleryFactoryHelper_medium.class at line 59 (galleryfactoryhelper_simple::newinstance)
in modules/core/classes/GalleryCoreApi.class at line 124 (galleryfactoryhelper_medium::newinstancebyid)

, check the g2_FactoryMap table in the database for references to the removed modules.

If this still don't solve your problem, a last resort would be to delete the cache directory located inside your g2data directory (this is where all the photos are stored so don't go and delete the folder album!!! Just the one named cache)!

I get Out of memory error when trying to crop a thumbnail, what should I do?

To crop the thumbnail for a very large image you may need to increase the memory limit for java. Java needs a parameter like -Xmx512M (this sets the limit to 512MB). In windows you can add this parameter in Control Panel / Java / Java tab / View.. for Java Applet Runtime Settings / Java Runtime Parameters.

I get the error 'Illegal mix of collations', what should I do?

If you get the error

Illegal mix of collations (latin1_swedish_ci,IMPLICIT) and (utf8_general_ci,COERCIBLE)

then you are probably using a buggy MySQL version. MySQL 4.1.16 and later as well as 5.0.17 and later have this bug fixed. Please see: . If you get this error during upgrade from G2.0.x or older to G2.1 or newer, please see: MySQL Upgrade Issue - UTF-8.

I enabled mod_rewrite, but it's not working, and now I can't get back to disable it - how else can I do this?

You have to modify the database manually. (You can use some web based tool do it, e.g. phpmyadmin) Login to your g2database, choose (g2_)PluginMap table. Here you have to modify the line of the rewrite module to deactivate it. To do this you can either: - manually select the line where g_pluginId is "rewrite", and turn the value of the g_active column into 0. or - run the following sql query:

UPDATE g2_PluginMap SET g_active=0 WHERE g_pluginId='rewrite';

After this, you might be ready, but you might also need to flush the cache manually. This can be done by visiting and choosing the "Cache Maintenance" option. If you couldn't access this directory either, go inside your g2data/cache folder on your server, and delete everything inside it, except derivatives dir.

I get ERROR_STORAGE_FAILURE when adding new photos or creating albums, what should I do?

In a mysql database this could be a problem with the g2_SequenceId table. To fix this in phpMyAdmin, find the g2_SequenceId table and click "Browse" to see the rows. If there are multiple rows click "Delete" for each row except the one with the largest value. If there is a single row then click the "SQL" button in the very upper left.. in the popup window type:

 select max(g_id) from g2_Entity

and click Go. Find the largest id in the query results. Now go back to "Browse" for g2_SequenceId and click "Edit" for the one row there. Change the value to be one larger than the maximum id reported in the query. Note that the errors received previously may have left directories and files inside your g2data/albums directory that are not displayed by Gallery. To complete the cleanup from this problem the items not shown when browsing the gallery as a site admin should be removed (backup first!).

The error can also occur if your mySQL is configured to only allow a certain amount of updates each given interval. The actual mySQL-error is 1226: User 'xxx' has exceeded the 'max_updates' resource (current value: xxxxx), but it's this ERROR_STORAGE_FAILURE that is shown in Gallery2. See: I seem to be running into some sort of MySQL query limit

The only thing you can do is to clean up (like it's explained above) and wait untill you can send update to your mySQL-server again.

If the error occur while displaying the gallery, check if you don't have any dead mysql process by stoping mysql and looking with ps -ef. If yes, simply kill the processes with kill -9 and start mysql.

I get a ERROR_PLATFORM_FAILURE, what should I do?

Most probably the filesystem permissions for your G2 storage folder (usually 'g2data') are incorrect. See: How can I fix the filesystem permissions of the Gallery storage folder?. In some cases the host has moved some files around and the G2data folder is in a different place. Verify that the correct path to the G2data directory in config.php.

    $gallery->setConfig('', '/Verify/this/path/to/g2data/');

If in some cases you try to add items and get a ERROR_PLATFORM_FAILURE turn debug on

  • If you get a error like: "mysqlt error: [1213: Deadlock found when trying to get lock; try restarting transaction]"
    • See if changing the the storage type helps; In config.php change the storage type to "mysql" instead of "mysqlt".

How can I fix the filesystem permissions of the Gallery storage folder?

Usually you get either an ERROR_PLATFORM_FAILURE or the upgrade wizard reports that the filesystem permissions are wrong for your storage folder, i.e. it can't write to all files and subfolders in that folder anymore.

  • To fix the problem, you can try the Fix the storage folder (make it writeable) tool in on the Filesystem Permissions page. (This tool was added in G2.1.1), older versions don't have it.
  • You can also try to change the permissions to 777 (read & writeable for everyone) with your FTP program. If all fails, please ask in the forum for help such that we can verify that it is indeed a filesystem permissions problem. If it actually is one, you'll have to ask your webhost to change the filesystem permissions recursively for you (e.g. chmod -R 777 g2data).
  • A common issue is:
in modules/core/classes/GalleryTemplate.class at line 270 (gallerycoreapi::error)
in modules/core/classes/GalleryTemplate.class at line 200 (gallerytemplate::_initcompiledtemplatedir)

In that case, if the above suggestions do not help, please try to delete g2data/smarty/templates_c/ folder via FTP or whatever tool you use to upload / manage files of your website.

  • If the problem does not disappear or is reappearing after it has been fixed for a while, please ask your webhost whether there are any scripts that change the owner of the files to the account owner. This could be the culprit since files are not created / managed by your account, but by the webserver application. We also welcome you to consult the Gallery forums for further expert advice.

I get an error in the installation step 8 (installing core module). What's wrong?

This can have various reasons.

  • The most common one is the following:
 Error (ERROR_BAD_PARAMETER) : something/gallery2/modules/core/classes/helpers/../../../../themes/matrix/

If you get this error, then something went wrong when uploading Gallery to your server.

Solution: Reupload the themes/ folder completely. At least themes/matrix/ with the files themes/matrix/MANIFEST, themes/matrix/, ... is missing. You should then get to a clean state: Delete the storage folder (g2data/) and drop the Gallery database or just its database tables. By doing that you ensure that everything is exactly how it should be before Gallery is installed. Then finally you can install Gallery by running the installation wizard again.

Why do I get a MySQL "Can't connect to local MySQL server through socket" error?

This indicates that PHP cannot communicate with your MySQL server. Check to make sure that MySQL is running, and verify that it's actually on the server where you think it is. If MySQL is running on your local system try using the IP address for your host (which should be instead of "localhost" for your database and see if that fixes the problem. For other diagnostics you can try, take a look at

"Sucessfully" uploaded images show a thumbnail, but display a black page when clicked on

I suddenly got an "ERROR_LOCK_TIMEOUT" message, what do I do?

  • Are you doing multiple things with your Gallery at the same time? E.g. uploading a lot of images in multiple browser Windows at the same time? Then this could explain why one of the Windows gets this message, it's blocked by the other task.
  • If there is no concurrent operation, then maybe an old 'lock' is still lying around in the Gallery system blocking everything else.
    • If you are using database locking (there is a setting at the bottom of 'Site admin' -> 'General' to switch between database and file based locking), then you can try to get rid of this old 'lock' by using phpMyAdmin to delete all rows of the 'g2_Lock' table.
    • If you are using file based locking, you can try to clear the caches to get rid of that 'lock'. See: How can I clear cached data?
    • Uninstall the image toolkits and delete that offending album. Install and activate the image toolkits and re add the items.
  • If you get a error like: "mysqlt error: [1213: Deadlock found when trying to get lock; try restarting transaction]"
    • See if changing the the storage type helps; In config.php change the storage type to "mysql" instead of "mysqlt".

PHP __FILE__ directive is not working correctly, what can I do?

Gallery depends on PHP's __FILE__ directive to return the absolute filesystem path of the current file. Due to a bug in PHP, __FILE__ returns a relative path in older PHP versions.

  • In most cases, you can fix the problem by convincing your webhost to upgrade the PHP version.
  • For some rare platforms, the bug still exists in the latest PHP version. In this case you need to file a bug report for PHP such that the bug gets fixed for that platform too. E.g. PHP 4.4.4 on SunOS 5.8 returns the filename without any path if any of the parent folders of your Gallery folder is not readable by the webserver user.

How can I clear cached data?

Gallery caches some data that doesn't change very often in its storage folder. This includes templates, data from the database and other things. To clear the template cache: login as admin, click site admin, click Maintenance, beside Delete template cache click run now.

To clear the cache in case something bad happened, browse to, (change example to your proper url) enter your Gallery setup password, select "Cache Maintenance" and delete the caches. Usually, selecting all but the Thumbnails and resizes (derivative) cache is a good idea (repeat: do not select the Thumbnails and resizes cache for deletion, rebuilding it takes quite a while for large Galleries).

With the introduction of template caching in G2.3, you might find that editing a template file will not have an effect. Login ad admin -> site Admin -> Performance, uncheck 'Enable template caching', click save. Click the Clear Saved Pages button. Reverse when completed with template editing.

What is the webserver error log?

Your Gallery runs as a PHP application on a webserver and when there is a fatal error, e.g. due to insufficient resources (memory, diskspace, execution time, ..), there is no chance Gallery can recover since the web-server just terminates the request. Symptoms usually are:

  • Blank / empty pages in the web-browser or
  • Browser-specific error pages (not to confuse with the Gallery application level error pages which always show a nicely formatted error page) or
  • When clicking on a link, the page doesn't change at all or
  • The browser offers you to download the current page (main.php) or
  • You might see something like Fatal error: Maximum execution time of or other PHP errors or
  • HTTP 500 internal server error pages

Webservers usually save such error events in their error log. This is very helpful to diagnose problems since the error log usually contains more information than what the symptom might reveal.

Apache stores this log as a file. As a webhosting customer, you can usually view the error log in the administrative section of your website (cPanel, Plesk, ..). If you can't find it, please ask your webhost / administrator for help.

How can I upload a theme or module via FTP when I used the preinstaller?

If you installed Gallery with the Pre-Installer, you need to first open the modules/ and themes/ directory for access before you can upload a theme or module manually yourself.

  1. Go to, sign in with your Gallery setup password and follow the "Filesystem Permissions" link.
  2. Click on "Add a new module or theme (make modules/ & themes/ writeable)" to open up your themes/ and modules/ folders.
  3. Now you can upload your theme or module via FTP.
  4. Finally don't forget to "close" the themes/ and modules/ folders again on the "Filesystem Permissions" page.
  • Note though that since Gallery 2.2, you can fetch new modules and themes directly via the Site Admin -> Plugins page. No FTP is needed anymore (unless for modules and themes that are not in the available repositories).
  • For multisites, lib/support/ is only available since Gallery 2.2
  • lib/support/ -> "Filesystem permissions" is only available since Gallery 2.1.1a (not yet in Gallery 2.1.0)

How to display PHP errors?

When diagnosing a problem, you want to be sure that you notice all hints that there might be. That's why you need to ensure that PHP is configured to display and log errors in such cases.

  • For Gallery 2.3.x and Gallery 2.2.x, it suffices to put Gallery into its debug mode. That's all you have to do. In debug mode Gallery gives lots of trace information about its execution path which is (in the first instance) not helpful when diagnosing a blank page. It will also, however, display stack traces and php errors, which are useful. If you're asking for help in the forums about blank-page problems don't post long execution traces, do post stack traces and/or php error messages.

Also see: * How can I view the error log of the webserver?

The rest of this section applies for older versions of Gallery and is unlikely to be relevant to anyone operating Gallery 2 in the modern era. It is retained here strictly for archaeological purposes:

  • In Gallery 2.0 and Gallery 2.1 (including 2.1.2), the debug mode doesn't enable displaying PHP errors yet. You'll need to enable it yourself.
  • In rare cases, you also have to ensure that PHP errors are not just displayed, but also logged.

By browsing to your Gallery's phpinfo page at -> PHPinfo, you can find all the configuration details of PHP we're interested in. And these are:

  • display_errors (we want it to be On or 1)
  • display_startup_errors (we want it to be On or 1)
  • log_errors (we want it to be On or 1)
  • error_log (it should be anything but undefined)
  • error_reporting (it should be 2047 or larger)
  • output_buffering (it should be 0 / Off)

You can ask your webhost to help you to put PHP into a configuration that is useful for debugging. Or you can open Gallery's main.php file in a text editor and replace:



 ini_set('display_errors', 1);
 ini_set('log_errors', 1);
 ini_set('error_log', dirname(__FILE__) . '/error_log.txt');

And then you need to put an empty textfile into your gallery folder and chmod it to 666 (give read+write permissions for everyone).

PHP errors, if any occur are then logged to that file.

Once you're finished with diagnosing and debugging your problem, you should remove those lines from main.php again and delete the error_log file as well.

How can I fix the problem with the Storage Directory Permissions reported by the Upgrade Wizard?

We check the filesystem permissions of your storage folder before we start the actual upgrade process. There are three common reasons that make this system check fail:

  • There is no versions.dat file in your storage folder. Fix: Create a versions.dat file in the storage folder.
  • How can I fix the filesystem permissions of the Gallery storage folder?
  • When installing Gallery, you maybe specified a relative instead of an absolute filesystem path for the storage directory. e.g. 'data', './data' or '../data/' when you should actually have entered '/some/path/to/data/' (Linux) or 'c:\some\data' (Windows). Since G2.1 we ensure that the path is stored as an absolute path, but if you are upgrading from an older versions you might have this issue. Fix: open config.php and change the path to be an absolute path. Then run the system checks step again.

Upgrading a Gallery that has been installed with the Pre-Installer

See Upgrading a G2 that has been installed with the Pre-Installer

How can I deactivate a module when I am unable to login?

  • First, please verify that you can't login anymore. If you can still login, you can deactivate modules at site admin -> Plugins.

If that fails, you have to modify the database manually. (You can use some web based tool do it, like phpmyadmin).

  1. Login to your g2database, choose (g2_)PluginMap table.
  2. Here you have to modify the line of the module you wish to deactive, e.g. "captcha" for the CAPTCHA module.
  3. Run the following SQL (NOTE: this is an example to deactivate the CAPTCHA module). You can do this even if you're using a web interface like phpMyAdmin, just click the "sql" tab.
UPDATE g2_PluginMap SET g_active=0 WHERE g_pluginId='captcha';
DELETE FROM g2_FactoryMap WHERE g_implModuleId='captcha';
  1. Finally, clear the database cache.

What do I do if I get a "Database Error" screen?

If you move servers or hosts, it is possible that you may encounter a "Database Error" screen, with the text "An error has occurred while interacting with the database.". If you're using Gallery2 with MySQL, this may be caused by having a different MySQL client library on your new machine/server. To attempt a fix, editing your config.php changing the line

 $storeConfig['type'] = 'mysqli';


 $storeConfig['type'] = 'mysqlt';