# Coppermine Photo Gallery v1.5.x: Documentation and Manual

# Errors

As with all applications, you may encounter various error messages if something goes wrong with the script or if you (or your users) have made a mistake handling the application.

## Error types

There are three types of errors that you may encounter:

- Soft errors
- Hard errors
- Unhandled errors

### Soft Errors

Soft errors usually happen if you (or the end user) will make a handling mistake. Coppermine will display an error message, but you can continue to browse the gallery. The soft errors are fully localized (i.e. they will be displayed in the language the user has chosen), so the programmers of Coppermine have (more or less) anticipated that such an error may happen under certain circumstances.

If you haven't set up at least one album where your uploads can go to and you click on the upload link, you will see there error message `Sorry there is no album where you are allowed to upload files`.

If you get a soft error and you're not sure what to do (maybe because the error message doesn't mean much to you), read up the corresponding section of this documentation and search the support board, as it is very likely that someone else has had the same issue you had.

In some sections of the documentation there are trouble shooting tipps that you should read up first if you get an error message, for example when you have issues with uploads or bridging.

### Hard Errors

Hard errors are messages that won't go away, usually because something is broken and needs fixing. This is usually the case if something is wrong with the database. As a result, you will see the dreaded "Fatal Error" message that usually doesn't mean much to unexperienced users.

If you obtain a hard error, you should act immediately and fix the error message asap.

Hard errors usually indicate that something is wrong which the programmers of coppermine could not foresee, that's why only a generic error message is being displayed. Read on to find out what you need to do.

### Unhandled Errors

Unhandled errors are the ones that usually are most tricky to solve, as they make the application coppermine crash in mid-air, without a meaningfull error message that could tell users what is wrong. This is usually the case if you get a blank page or just a template error.

## Fatal error

The message "Fatal Error" is a generic error message that just says that there is something wrong. It usually is a hard error - you won't be able to continue using coppermine unless you fix the reason for the error message. The reasons for such a generic error message are manifold. For security reasons (to make sure that a possible malevolent attacker of the site could not abuse potential vulnerabilities), the "real" error message is not being displayed by default, but only the generic "Fatal Error" message. For you as coppermine admin it's mandatory to find out what actually is wrong. To do so, you need to enable debug_mode in Coppermine's config, as this will result in the "real" error message being displayed.

### Enabling debug_mode in Config

To enable debug_mode, go to coppermine's config and enable debug_mode there by expanding the section "Miscellaneous settings", scroll to the bottom of the screen and select "Enable debug mode" there. Leave "Notices display" turned off.

In some cases, you might not be able to access the config page any longer to enable debug_mode as suggested in this section, so you will have to enable debug_mode manually. Refer to the next section to find out how this is being done.

### Manually enabling debug_mode

If you need to enable debug_mode, but can no longer access the config screen (maybe because of the fatal error that stops the config page from displaying or maybe because your admin login doesn't work as expected no longer), you can enable debug_mode manually as well.

To accomplish this, you will need a third-party tool like phpMyAdmin to directly manipulate your database. Many webhosts provide phpMyAdmin or a similar tool in their webcontrol panel. You may want to take a look there or ask your webhost if they provide it to you for free. If they don't, you should install that application, as it is helpful not only for troubleshooting coppermine, but all kinds of database administration purposes. Be aware though that this tool is very powerfull and directly manipulates the database and can therefore delete or otherwise damage your database if not used properly. Among other things, phpMyAdmin can be used to back up your database as well. Please refer to the phpMyAdmin documentation on all questions related to the install, setup and use of phpMyAdmin - the coppermine support board definitely is not the right place to ask questions how to set up phpMyAdmin.

This being said, let's assume that you already have phpMyAdmin available or that you have successfully installed it right now. To actually enable debug mode manually, follow these steps:

- Point your browser to the folder phpMyAdmin resides in on your server (e.g. `http://example.com/phpMyAdmin/`)
- Depending on the security mechanisms that you have set up during phpMyAdmin's initial configuration, you may have to authenticate your access. This authentication is very important to make sure that no unauthorized access to phpMyAdmin takes place; as suggested before, a malevolent user could ruin your entire site if he got access to a database manipulation tool like phpMyAdmin.
- If you have more than one database available, choose it at the top of the left frame. If you have only one database, all tables that reside in your database will instantly be visible in the left frame
- Click in the left frame on the database table that contains coppermine's configuration. The name of the table is "cpg15x_config" or similar (depending on the table prefix you chose during installation).
- In the main frame of phpMyAdmin (the most right one), click on the tab "Browse" at the very top
- The individual entries of the table should be displayed. Scroll down to see the line "debug_mode". As phpMyAdmin usually only displays a particular number of rows per page, you might have to continue to the second or third page of entries, using the navigation at the top or bottom of the screen
- Once you have found the row labelled "debug_mode", click on the edit icon (the pencil icon) in that row.
- On the edit screen, change the value from "0" (which means "Don't display debug_mode") to "1" (which means "Display debug_mode for everyone") and then save your changes by clicking on the "Go" button.
- You can now leave phpMyAdmin and return to your coppermine screen - debug_mode should be enabled
- With debug_mode enabled, reproduce the error message: this time, you should not only get the generic "Fatal error"-message, but an explanation as well what actually went wrong.

Now you can use the actual error message that indicates what is wrong to troubleshoot - fix the error if you can. If you can't fix it by yourself, search the coppermine support board for the error message (the generic part, not the specific part that only applies to your database/site). It is very likely that someone else used to have the same issues you experience - heed the advice given on the thread that describes your error message.

Once you're done and the error message has gone away, don't forget to turn debug_mode off again. If your gallery is fully operational again (it should be after having fixed the error), you can go to coppermine's config and turn debug_mode off. If you can't access coppermine's config (maybe because you have forgotten your admin account details), use the same method described above to turn debug_mode off manually (using phpMyAdmin): browse coppermine's config table, search for "debug_mode", edit that entry and change "`1`" back to "`0`".

### Turning debug_mode off

The debug_mode output itself is not an error message. Just the debug_output being there without an actual error message showing through the debug_output doesn't mean that there is something wrong: by default, debug_mode is off. If you don't have any particular problems with your gallery and there are no actual errors to fix, turn debug_mode off in config or manually, just the same way you turned it on in the first place.

## Common error messages

There are some error messages that are often being encountered. Although they are more or less self-explanatory, some users appear not to be able to make heads or tails out of them, so here is an incomplete list with suggested fixes.

### Database-related error messages

Error message | Possible cause | Suggested fix
--- | --- | ---
`Can't create/write to file '/tmp/#sql_45d5_0.MYI'` | MySQL can't create a temporary file for the result set in the given temporary directory. | Alter the tmpdir variable to point to a writable directory. It requires changing the tmpdir line in the my.cnf file, usually in the [mysqld] section (tmpdir = /writable/dir, where /writable/dir is a directory to which you can write). Ask your webhost to make the above changes, as only the administrator of the server where the mySQL database runs on can perform this operation.
`Can't open file: 'yourPrefix_tableName.MYI'` | Your database table is corrupted. | This is not a coppermine issue, but a mySQL issue. It just may affect a database table used by Coppermine. Use your website's Control Panel to repair the table, or use phpMyAdmin to execute this sql query: `REPAIR TABLE yourPrefix_tableName` (Replace yourPrefix_tableName with your table name, e.g. cpg145_pictures) If you don't understand the solution, ask your webhost to make the above changes.
`Got error 28 from storage engine` | No space left on device, i.e. the hard disk where your database resides on is full. | This is not a coppermine issue, but a mySQL issue. Contact your webhost or the person who is in charge of running the server where your database resides. Tell that person about the error message you get - he/she should know what to do. Basically, you have to free up some space or clean the database. Please note that you can not do this on your own when webhosted - only the server operator can perform this action.
`Table 'yourPrefix_tableName' is marked as crashed and should be repaired` | Your database table is corrupted. | This is not a coppermine issue, but a mySQL issue. It just may affect a database table used by Coppermine. Use your website's Control Panel to repair the table, or use phpMyAdmin to execute this sql query: `REPAIR TABLE yourPrefix_tableName` (Replace yourPrefix_tableName with your table name, e.g. cpg145_pictures) If you don't understand the solution, ask your webhost to make the above changes. If this happens frequently, there is something fishy with your webserver - ask your webhost for support as well.

For a complete list of mySQL error messages shining through Coppermine's output, refer to MySQL 5.1 Reference Manual → B Errors, Error Codes, and Common Problems → B.3 Server Error Codes and Messages.

### Common PHP errors

There are a lot of people (especially PHP newbies) that post questions like `I get the error "Parse error: parse error in XXX"` and don't know what to do about it. That's why I translated this list of common errors (and a solution how to fix them) from the original german article in Dr. Web

Error message | Possible cause | Suggested fix
--- | --- | ---
`Parse error: parse error in C:\Apache\htdocs\read.php on line 8` | This error message refers to an error in the PHP syntax. | You probably forgot to end a line with `;` or you have too many brackets opened or closed (`{`).
`Fatal error: Call to unsupported/undefined function ... in C:\Apache\htdocs\read.php on line 8` | This error means that the function your script was going to use isn't defined in the current PHP version with modules, or if you're using user-defined functions that your function hasn't been defined yet. | This is usually caused if you forgot to include the function definition.
`Warning: Wrong parameter ... for ... in C:\Apache\htdocs\read.php on line 8` | You have handed over too many (or the wrong) parameters to the function. | If it's a built-in php-function, check the manual; to see if it's a user-defined function, then recheck your code.
`Warning: Cannot add header information - header was already sent ... in C:\Apache\htdocs\read.php on line 4` | You had some text output first (e.g. the doctype declaration or `<html>`) and called the function header() afterwards. | This is most often the case when using cookie stuff. Remember you can not use header() twice!
`Parse error: parser stack overflow in C:\Apache\htdocs\read.php` | PHP is out of memory. | This usually happens if you built an eternal loop, especially when using include statements.
`Warning: fopen("file.txt","r+") - No such file or directory` | The requested file or directory doesn't exist. | Check the spelling (accuracy counts here).
`SAFE MODE Restriction in effect. The script whose uid is XXX is not allowed to access...` | The safe mode is switched on. Some functions in the upload systems can't be used. | Usually your webhost has put safe mode in place (often not correctly configured). Try switching silly_safe_mode on.
Funny characters like `ï»¿` shine through the output on some or all pages | A Byte Order Mark (BOM) has crept into one of your coppermine files | This usually happens if you edit unicode-encoded files (which is what coppermine's core files are) with an editor that is not designed to be used to edit Unicode files. Most notoriously notepad.exe (which comes with Microsoft's Windows). The BOM might shine through on the page that you have manually edited, but it may show as well on pages that you're not aware of. Undo your edit if you can and use an editor that can handle utf-8 encoding (for a list of editors, refer to Tools recommended by the devs → Text editors). If you can't remember what you have edited, search for the BOM in all of your files. Emurasoft's application Replace in files is a good tool to accomplish this on Windows-driven machines.

### Upload-related error messages

There is an entire sub-section dedicated to upload-related error messages on the upload troubleshooting page.

### Webserver response codes

Most internet sites are driven by Apache webservers, that's why the term "Apache server response codes" is quite well known as well. Most web surfers are familiar with the dreaded 404 not found and 500 internal server error messages. In most cases, those errors are not related to Coppermine in itself. Below is a list of apache webserver response codes and an explanation of those codes. Please understand that a response code in itself doesn not mean that there is something wrong - most codes are silent, i.e. an end user doesn't see them, as they are part of the handshake between the server and the client. The list below is incomplete and only shows actual error messages.

Please understand that this section of the docs goes unsupported on the Coppermine support board - if you need more details on the webserver response codes, read up the excellent apache documentation or the Wikipedia list of HTTP status codes.

Response code | Category | Explanation | Suggested fix
--- | --- | --- | ---
#### 400 Bad Request | Client Request Error | There is a syntax error in the request, and it is denied. | This should hardly ever happen, as the error message means that there is something wrong with the communication between client (browser) and server. Just try again. If this doesn't help, try using another browser.
#### 401 Authorization Required | Client Request Error | The request header did not contain the necessary authentication codes, and the client is denied access. This error message is similar to the 403 Forbidden, but is specifically meant for cases where authentification is possible, but has failed or was not provided. | n/a
#### 403 Forbidden | Client Request Error | The request was a legal request, but the server is refusing to respond to it, i.e. the client is not allowed to see a certain file. This is also returned at times when the server doesn't want any more visitors. | This error usually is an indicator for permissions on file system level not applied correctly. Other possible reasons can be permission restrictions imposed by a custom `.htaccess`-file. In rare cases, this error can be caused as well by ownership issues (CHOWN), which can usually only be resolved by the webserver administrator, i.e. the webhost on shared webhosting accounts.
#### 404 Not Found | Client Request Error | The requested file could not be found (but may be available again in the future). Possibly because it was deleted, or never existed before. Often caused by misspellings of URLs. Keep in mind that capitalization matters on most webserver operating systems. | Check if the requested file actually is there.
#### 405 Method Not Allowed | Client Request Error | The method you are using to access the file is not allowed. Examples: using GET on a form which requires data to be presented via POST, or using PUT on a read-only resource. | This error should not apply for stable Coppermine releases, as all forms that exist in the core code have been tested thoroughly. If it does exist for you though and you think that the reason lies in Coppermine's core code, please report back on the Coppermine support board.
#### 406 Not Acceptable (encoding) | Client Request Error | The requested resource is only capable of generating content not acceptable according to the Accept headers sent in the request, i.e. the requested file exists but cannot be used as the client system doesn't understand the format the file is configured for. | This error should not apply for stable Coppermine releases.
#### 408 Request Timed Out | Client Request Error | he server timed out waiting for the request.[2] According to W3 HTTP specifications: "The client did not produce a request within the time that the server was prepared to wait. The client may repeat the request without modifications at any later time." In other words: the server took longer than it's allowed time to process the request. | This is often caused by heavy net traffic. Try again later. If this happens frequently, consider upgrading your webhosting contract or moving to a better webhost.
#### 409 Conflict | Client Request Error | Indicates that the request could not be processed because of conflict in the request. Can be an indicator for too many concurrent requests for a single file. | n/a
#### 410 Gone | Client Request Error | The file used to be in this position, but is there no longer. This response code indicates that the resource requested is no longer available and will not be available again. This should be used when a resource has been intentionally removed; however, it is not necessary to return this code - a 404 Not Found can be issued instead. Upon receiving a 410 status code, the client should not request the resource again in the future. Clients such as search engines should remove the resource from their indexes. | n/a
#### 411 Length Required | Client Request Error | The request is missing its Content-Length header. | n/a
#### 412 Precondition Failed | Client Request Error | A certain configuration is required for this file to be delivered, but the client has not set this up. | n/a
#### 413 Request Entity Too Long | Client Request Error | The requested file was too big to process, i.e. the request is larger than the server is willing or able to process. | If this happens for a Coppermine page, review your webserver's setup. If the server isn't yours to administer (i.e. if you're webhosted), ask your webhost for support.
#### 414 Request URI Too Long | Client Request Error | The URI provided was too long for the server to process. |
#### 415 Unsupported Media Type | Client Request Error | The filetype of the request is unsupported. Example: the client uploads an image as `image/svg+xml`, but the server requires that images use a different format. | If this happens for a Coppermine page, review your webserver's setup. If the server isn't yours to administer (i.e. if you're webhosted), ask your webhost for support.
#### 450 Blocked by Windows Parental Controls | Client Request Error | A Microsoft extension. This error is given when Windows Parental Controls are turned on and are blocking access to the given webpage. | n/a
#### 500 Internal Server Error | Server error | Nasty response that is usually caused by a problem in the code when a CGI program is run, or if the code runs into a limitation imposed by the server-configuration. | If you can, you should review the server's error log (not Coppermine's log!) for details what actually went wrong. Usually, when webhosted (i.e. if the server is not yours to administer), you don't have access to those logs, so you better ask your webhost for support. Usually, this message shows for Coppermine-driven pages if you run into server-sided limitation as far as the memory consumption is concerned, i.e. if you fed the script a bite that is too big to chew. In 90% of all cases, this happens when trying to process an image that is too big in terms of resolution.
#### 501 Not Implemented | Server error | The request cannot be carried out by the server. | If this happens for a Coppermine page, review your webserver's setup. If the server isn't yours to administer (i.e. if you're webhosted), ask your webhost for support.
#### 503 Service Unavailable | Server error | The service or file that is being requested is not currently available, i.e the entire server is currently unavailable (because it is overloaded or down for maintenance). Generally, this is a temporary state. | Ask your webhost for support if this error message is displayed permanently.
#### 509 Bandwidth Limit Exceeded | Server error | This status code, while used by many servers, is not specified in any RFCs. Apache bw/limited extension. | Ask your webhost for support!