# 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`".

## 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.
`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.

### 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'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.