编辑“Gallery2:FAQ”（章节）

=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 [http://gallery.menalto.com/forum forums]. If that doesn't help, you probably want to ask for help in the support forum. Include [[Gallery:Gallery2:faq#What_information_is_required_when_I_ask_for_help_in_the_forums.3F|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 [[Gallery:Gallery2:FAQ#How_can_I_make_sure_that_my_installation_files_are_all_intact.3F|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 {{exampleurl|/upgrade/index.php}} or {{exampleurl|/install/index.php}} 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  [[Gallery:Gallery2:FAQ#What_about_the_warning_for_missing_.26_modified_files_in_the_installer_.26_upgrader.3F|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: [[Gallery:Installing_an_Image_Processing_Library|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.
* 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 [[Gallery:Gallery1:FAQ#Why_do_I_get_the_error_Allowed_memory_size_of_Xxx_bytes_exhausted.3F|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 [[Gallery:Gallery2:Modules:squarethumb|Square Thumbnails 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. [[Gallery:Gallery2:faq#How_to_set.2Fuse_Gallery_in_debug_mode.3F|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 Deactivate AND Uninstall "Url Rewrite" in Admin Panel(Plugins).  This seems to be host-dependent.

==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 [http://drupal.org/node/32072 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 [[Gallery:Gallery2:faq#MySQL_.22Client_does_not_support_authentication_protocol.22_error|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:
* http://gallery.menalto.com/node/42359#comment-160706

==I get only a blank screen when trying to view my Gallery, what's wrong?==
This can have various reasons. The first thing you should check is 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:
* [[Gallery:#How_to_display_PHP_errors.3F|How to display PHP errors?]]
* [[Gallery:#PHP_memory_limit_-_Why_do_I_get_the_error_Allowed_memory_size_of_Xxx_bytes_exhausted.3F|How to check / increase the memory limit?]]
* [[Gallery:#What_is_the_webserver_error_log.3F|How can I view the error log of the webserver?]]
* [[Gallery:#How_to_set.2Fuse_Gallery_in_debug_mode.3F|Always enable the 'buffered' debug mode first if there is a problem]]

==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: 
 C:\> cacls %COMSPEC% /E /G %COMPUTERNAME%\IUSR_%COMPUTERNAME%:R 

This adds the "read" permission to the IIS-user for the cmd.exe. Close the prompt and then try activating the imagemagick module again. [[Gallery:Gallery2:Installation on Windows Server 2003 and IIS6#Installing Binaries|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/> 
 LayoutHeaderOff 
 LayoutFooterOff 
 </Directory>

==How to set/use Gallery in debug mode?==
Edit your config.php and turn on buffered debug mode like this: 

 $gallery->setDebug('buffered');

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 [[Gallery:Gallery2:InstallationErrors|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 [http://bugs.php.net/32290|PHP 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 {{exampleurl|/lib/support/index.php}} -> "Reset User Password" (since Gallery 2.3) which points to {{exampleurl|<nowiki>/main.php?g2_view=core.UserAdmin&g2_subView=core.UserRecoverPasswordAdmin</nowiki>}}

=== "You must enter the letters appearing in the picture." ===
If you see this error message, then you either ignored the [[Gallery:Gallery2:Modules:captcha|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 [[Gallery:#How_can_I_deactivate_a_module_when_I_am_unable_to_login.3F|deactivate it manually]].
=== "Incorrect letters." ===
This error message is shown if you didn't interpret the [[Gallery:Gallery2:Modules:captcha|CAPTCHA]] image correctly.
* Please enter the letters and numbers from the CAPTCHA image into the input field below and try to login again.
=== 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 http://www.whatsmyip.org/mod_gzip_test/ 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 [http://gallery.menalto.com/node/35431#comment-129385 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 {{exampleurl|/gallery2}} 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. ''<nowiki>http://mygallery.com/</nowiki>'', 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 http://gallery.menalto.com/node/36605#comment-133101 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:
 zend_optimizer.optimization_level=15
with:
 zend_optimizer.optimization_level=14

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: 
* [http://gallery.menalto.com/node/33076 How to handle references in PHP 4.4.0]
* [http://www.zend.com/products/zend_optimizer Latest Zend Optimizer Version]
* [http://php.net/manual/en/language.references.php PHP Manual: References Explained]

==MySQL "Client does not support authentication protocol" error==
The reason for this is explained and several solutions are presented on this page: [http://dev.mysql.com/doc/mysql/en/old-client.html 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 [[Gallery:Gallery2:Download#Modules|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 [http://gallery.menalto.com/downloads Gallery Download Page].
* When you connect with your web browser to <nowiki>http://www.example.com/gallery2/gallery_remote2.php</nowiki> you get a nice-looking page that says the page is not found. See the [[Gallery:http://codex.gallery2.org/index.php/GalleryRemote:FAQ#Connecting_to_a_G2_installation:_Server_contacted.2C_but_Gallery_not_found_at_this_URL 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 <b>Windows</b> machine, start the path with the drive letter (e.g. c:\ )
*If you are on a <b>shared host</b> 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: http://gallery.menalto.com/node/37060#comment-135509
-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: 
:# [[Gallery:#How_do_I_prevent_users_from_accessing_my_site_during_maintenance_or_upgrades.3F|Put G2 into maintenance mode]]
:# Browse to <nowiki>http://www.example.com/gallery/main.php?g2_view=core.PluginCallback&g2_pluginId=rewrite&g2_pluginType=module&g2_command=deactivate</nowiki>
(replace www.example.com/gallery2/ with the URL of your own Gallery2 installation)

For versions before G2.2, use this URL instead: <nowiki>http://www.example.com/gallery2/main.php?g2_controller=core.AdminModules&g2_moduleId=rewrite&g2_action=deactivate</nowiki>

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 <nowiki>http://www.example.com/gallery/main.php?g2_controller=core.UserLogin&g2_form[formName]=UserLogin&
g2_form[action][login]=Login&g2_form[username]=admin&g2_form[password]=secret</nowiki> (replace "secret" with your own password)

If you '''still''' get an error (ERROR_MISSING_OBJECT), go to <nowiki>http://www.example.com/gallery/lib/support/</nowiki>.  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 <nowiki>http://www.example.com/gallery2/lib/support/phpinfo.php</nowiki> 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: <nowiki>http://www.example.com/gallery2/main.php?g2_controller=core.AdminThemes&g2_form[action][saveDefaults]=1&g2_form[default][theme]=matrix</nowiki>
::(replace www.example.com/gallery2/ with the URL of your own Gallery2 installation)

This will only work if you are already logged in as administrator. See [[Gallery:Gallery2:FAQ#Images_don.27t_show_up_and_the_album_.2F_photo_links_don.27t_work.2C_what_can_I_do.3F|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 [http://bugs.php.net/bug.php?id=34635 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 ([http://us3.php.net/configuration.changes 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 [http://gallery.menalto.com/node/39810  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 [[Gallery:Gallery2:FAQ#What_information_is_required_when_I_ask_for_help_in_the_forums.3F|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?==
{|class="gallery" style="background-color: #eee; width:90%"
!Problem!!Solution
|-
|A movie is not playing in Firefox but it plays in Internet Explorer
|Probably you're dealing with a .avi video. Microsoft has not supported Windows Media in FireFox until recently. You have several options to fix this:
* Either install the WMP plugin for FireFox [http://port25.technet.com/pages/windows-media-player-firefox-plugin-download.aspx/ WMP in FF]
* Or install an alternative video player like [http://www.videolan.org/vlc/ VLC]
* Or change the 'mime settings' of QuickTime Player to play .avi files as well.
|-
|When the apache2 mod_deflate module is enabled, movies most likely don't start playing in Internet Explorer (and possibly also in other browsers).

The Apache2 RemoveOutputFilter directive removes any output filter associations for files with the given extensions. This allows .htaccess files in subdirectories to undo any associations inherited from parent directories or the server config files.
The extension argument is case-insensitive, and can be specified with or without a leading dot.
More info on this: [http://httpd.apache.org/docs/2.0/mod/mod_mime.html#removeoutputfilter Apache2 documentation]
|Put a '.htaccess' file in your g2 root directory with the following line in it:
 RemoveOutputFilter wmv avi mpg mpeg
::Note: if the .htaccess file already exists, add this line at the beginning
::Note: add additional extensions as needed
|-
|Without the [[Gallery:Gallery2:Modules:ffmpeg|ffmpeg module]] active, movies are not playing inline, you only see a Download link.
|Go to "edit movie", and set movie dimensions manually. If dimensions aren't set, the embedded movie player feature will not work for this item.
|-
|Movie dimensions are set in ''Edit Movie'' etc but you only see the Download movie link. 
|Your browser isn't configured to play movies embedded in the browser. You need to configure Firefox/Internet Exploret/ to play movies embedded in the browser (browser plug-ins).
|}

== 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 <nowiki>http://example.com/gallery2/lib/support/</nowiki>, enter your password, click there on cache management and delete the db and template cache. Of course you need to replace example.com/gallery2/ 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 [[Gallery:Gallery2:Download|Download Page]].
* For 3rd party / non-official themes, please check the [[Gallery:Gallery2:UserContributions|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: http://bugs.mysql.com/bug.php?id=10446 .  If you get this error during upgrade from G2.0.x or older to G2.1 or newer, please see: [[Gallery:Gallery2:Known_Issues:MySQL_UTF8_Upgrade|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 <nowiki>http://yourgalleryurl.com/lib/support/</nowiki> 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 <i><code>1226: User 'xxx' has exceeded the 'max_updates' resource (current value: xxxxx)</code></i>, but it's this ERROR_STORAGE_FAILURE that is shown in Gallery2. 
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:
[[Gallery:Gallery2:FAQ#How_can_I_fix_the_filesystem_permissions_of_the_Gallery_storage_folder.3F|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('data.gallery.base', '/Verify/this/path/to/g2data/');

== 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 <nowiki>http://example.com/gallery2/lib/support/</nowiki> 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).

* What might help is removing all cached data from the storage folder. Please see: [[Gallery:#How_can_I_clear_cached_data.3F|How can I clear cached data?]]

* A common issue is:
 Error (ERROR_PLATFORM_FAILURE) :
 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/theme.inc
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/theme.inc, ... 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 127.0.0.1) instead of "localhost" for your database and see if that fixes the problem.  For other diagnostics you can try, take a look at http://dev.mysql.com/doc/refman/5.0/en/can-not-connect-to-server.html

== "Sucessfully" uploaded images show a thumbnail, but display a black page when clicked on ==
* [[Gallery:Gallery2:FAQ#PHP_memory_limit_-_Why_do_I_get_the_error_Allowed_memory_size_of_Xxx_bytes_exhausted.3F|Increase the PHP memory_limit]]
* [[Gallery:Gallery2:FAQ#Thumbnails_.2F_resized_images_don.27t_get_generated_properly.2C_how_can_it_be_fixed.3F|Change the image toolkit priority]]

== 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: [[Gallery:#How_can_I_clear_cached_data.3F|How can I clear cached data?]]

== 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 cache in case something bad happened, browse to {{exampleurl|/lib/support/index.php}}, 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).

== 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.
# Go to {{exampleurl|/lib/support/index.php}}, sign in with your Gallery setup password and follow the "Filesystem Permissions" link.
# Click on "Add a new module or theme (make modules/ & themes/ writeable)" to open up your themes/ and modules/ folders.
# Now you can upload your theme or module via FTP.
# 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.

* Starting with Gallery 2.2, it suffices to [[Gallery:#How_to_set.2Fuse_Gallery_in_debug_mode.3F|put Gallery into its debug mode]].
* 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.
Also see: * [[Gallery:#What_is_the_webserver_error_log.3F|How can I view the error log of the webserver?]]

By browsing to your Gallery's phpinfo page at {{exampleurl|/lib/support/index.php}} -> 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:
  <?php
with
  <?php
  ini_set('display_errors', 1);
  ini_set('log_errors', 1);
  ini_set('error_log', dirname(__FILE__) . '/error_log.txt');
  error_reporting(E_ALL);
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: [[Gallery:Gallery2:How_To_Restore_From_Backup#Restoring_Gallery_2_from_a_full_backup|Create a versions.dat file]] in the storage folder.
* [[Gallery:#How_can_I_fix_the_filesystem_permissions_of_the_Gallery_storage_folder.3F|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 data.gallery.base 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 [[Gallery:Gallery2:Preinstaller#Upgrading_a_G2_that_has_been_installed_with_the_Pre-Installer|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 [[Gallery:#I_can.27t_login_anymore.2C_what_can_I_do_now.3F|can't login anymore]]. If you can still login, you can deactivate modules at site admin -&gt; Plugins.

If that fails, you have to modify the database manually. (You can use some web based tool do it, like phpmyadmin).
# Login to your g2database, choose (g2_)PluginMap table.
# Here you have to modify the line of the module you wish to deactive, e.g. "captcha" for the CAPTCHA module.
# 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';
# Finally, [[Gallery:#How_can_I_clear_cached_data.3F|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';
to
  $storeConfig['type'] = 'mysqlt';


[[Gallery:Category:Gallery 2:Troubleshooting|FAQ]]
[[Gallery:Category:Gallery 2:Usage|FAQ]]