Troubleshooting first steps

ozh edited this page Mar 28, 2016 · 2 revisions

Facing a problem? Something isn't working as expected? Before submitting a new issue, take your time and follow these few steps.

Double check your config.php

99% of the time, errors are caused by a user error in their config file or server configuration. Double check your config, read the readme and all the pages here in this wiki.

Disable plugins

Make sure one of your plugins isn't causing the issue. Disable them all, see if things works, and if so, re-enable plugins one by one with tests each time till you find the culprit. It could be either a plugin on its own, or two plugins conflicting with each other.

Enable debugging mode

By default, most error messages are hidden in YOURLS, and this may end up with a blank screen (ie the dreaded White Screen Of Death). Turn debugging on to display any error or warning, with the following line anywhere in your config.php:

define( 'YOURLS_DEBUG', true );

Check server logs

If the error is produced on the server side (ie the page is generated with an error), most of the time you will find valuable information in the server logs.

Depending on the server software and configuration, this text file may be located somewhere like /var/log/apache2/error.log, /usr/local/apache/logs/error_log, /xampp/apache/logs/error.log, etc...

If you don't know where the error log is, you can look for the ErrorLog directive in the Apache configuration. If you don't know how to do this, ask your server admin.

Use your browser developer tools

If the error is produced on the client side (ie the page is generated fine, but when you try to interact with it, something wrong happens), hunt for Javascript errors in Ajax requests.

Depending on your browser, this can be done with the Firebug extension in Firefox, with Chrome DevTools, ... You'll find plenty of guides explaining how to do so (eg how to debug ajax chrome)

Try another database engine

If the error seems to be database related, try to switch to another database engine and see if the error message disappears or at least gets more helpful. Add one of the following lines anywhere in your config.php:

define( 'YOURLS_DB_DRIVER', 'pdo' ); // default setting if nothing specified
define( 'YOURLS_DB_DRIVER', 'mysqli' );
define( 'YOURLS_DB_DRIVER', 'mysql' );

STFW after you have RTFM

When you have Read The Fine Manual but are still lost, please Search The Fine Web. Thousands of people have probably faced the same situation before and it may be documented already.

Submit proper issues

Submitting an issue that is improperly or incompletely written is a waste of time for everybody. It's nothing complicated so please read the Contributing Guide before anything.