How to troubleshoot (read this first)

Before panicking or posting questions to the forum, here are a few ways and places you can look for clues to your problem.

Set a man a fire and he's warm for a night. Set a man afire and he's warm for the rest of his life.

1. Stop and think. As ever, identify what changes you've made recently, what new modules may have been installed. Most of the time something seems to go wrong, it's your fault. Remember that :-) and avoid those "Doh" moments after posting your problem. Are you SURE the modules you installed are the right versions?
2. Read the errors. If pages are just not displaying, see your server logs. Find them, read the last few entries to see what's going wrong. Errors like the following can be found there:
   • .htaccess config problems - "Internal server error" - Error 500 directive not allowed here
   • Memory problems Fatal error: Allowed memory size of 8388608 bytes exhausted
   • Misbehaving javascript - modules/troublesome/utility.js 404 file not found.
3. Validate your page If it's a layout problem - alignment, font size, overflowing blocks etc - For the love of Mike run it through the validator. Validation is a target to aim at, but admittedly not always easy to achieve. However, you should know what errors exist, and how important they are. Specifically, close all tags correctly and fix structural problems. The rest of the complaints about entities and invalid attributes are less of an issue. If it's a non-public dev site get the web developer toolbar and use the "Validate local HTML" option. Get the web developer toolbar anyway, and use the CSS inspector to find out what styles apply to which elements.
   • Bring up the DOM inspector [CTRL-SHIFT-I].
   • Use the 'Select element by click' pointer and click on the problem element.
   • Navigate the DOM tree to ensure it's the right element.
   • Select 'CSS Style Rules' from the right pane where it says 'Object - DOM Node'.
   • Click through the 'Rules' and find out all the places where the element gets its formatting from. The rule at the bottom takes precedence. Learn about the first 'C' in CSS - the Cascade.
   • Check out the same for the container and child elements - one items margin may be another items padding. (List items especially).
   • If you find unwanted css coming from a core Drupal css - over-ride it in your own style.css with the same rule pattern, don't hack core.
4. Read the README. No, Really. Although many modules can 'just work' on installation, some bits (like enabling HTMLTidy under WYSIWYG) need an extra step or two. It's not broken, it's documented in the README. Some modules have dependancies on server PHP extensions or assume other modules are available (eg 'forum.module' assumes 'comment.module' is available, and dies if you turn them off). The README should mention this. Some modules have potential conflicts, or may even require patches to other modules (see img_assist + tinyMCE). Again, the answer may be hidden in plain sight. Avoid the head-slap moments and read everything you can that came with the module.
5. Search for the proper way. If the error you see (in the log or the screen) doesn't make sense to you, try a search on it. Use Google, and quote the error as best you can. Google: "Argument #1 is not an array" drupal. - A google on a phrase, plus the keyword 'drupal' is probably better than a drupal.org search. Take care to leave out pathnames (but filenames are probably useful). Try different permutations of quotes around what seem to be discreet parts of the message. Try searching both with and without arguments. Strings input by the user won't help much when searching for the problem elsewhere.
6. Identify the source of the problem. You have an error in your SQL syntax; check the manual that corresponds to your MySQL server version for the right syntax to use near '(n.nid), n.title FROM category c INNER JOIN category_node r ON c.cid = r.cid INN' at line 1 query: SELECT c.*, r.DISTINCT(n.nid), n.title FROM category c INNER JOIN category_node r ON c.cid = r.cid INNER JOIN category cn ON c.cnid = cn.cid INNER JOIN node n ON c.cid = n.nid INNER JOIN node cnn ON cn.cid = cnn.nid WHERE n.status = 1 AND n.moderate = 0 ORDER BY cn.weight, cnn.title, c.weight, n.title in /var/www/html/doadance/drupal/includes/database.mysql.inc on line 120. Errors like the above are not caused by drupal database.inc. They are simply found by it because a module has sent some bad instructions to the internals. We need to find where the call came from, unfortunately you won't get a call stack by default. Try to identify the table being addressed in this query to see what module may be doing it. In this case it looks like category, but it may in fact be any other module that's trying to directly access data about categories.
7. Dump some diagnostics. Debugging. If you are really trying to find the causes, it may help to display some of the code.
   • Try the devel.module
   • For one-off quick hacks, when you just want to know why you are seeing (EG): warning: in_array() [function.in-array]: Wrong datatype for second argument in /home/httpd/global/drupal/modules/node.module on line 1303. Try some lightweight code.
   • Go look at that file. Modify it a bit. It's safe to do so if you remember to undo afterwards.
   • On line 1303, node.module we find in_array('status', $node_options).
   • on the line before try inserting the code: print("Node options are : '".print_r($node_options,1)."'"); and see if that gives any clue.
   • A useful data dump when debugging, even within node pages themselves is sometimes. print("Node is : ".print_r($node,1)");
8. Ask the right questions. When posting questions on the Drupal forum, it's usually better to post more info than less. The more work you can demonstrate has gone into solving it already, the more likely folks are to help you get the rest of the way. Do ask questions "The smart way". Do follow up in the same thread if you resolve it - even if no-one else posted. Do consider submitting your solution as a comment under Troubleshooting FAQ or the elsewhere in the handbook. In Drupal, it's usually important to know if you are on a shared hosting provider - mention this!
9. Identify the module that's giving you problems. All Drupal 'pages' are dynamically created to one extent or another. The URL where dynamically created pages are published is usually defined in a module's hook_menu() implementation. When installing or investigating new modules, it's usually interesting to open up the code and look at the ***_menu() function to see what it does. Conversely, if you want to find which module is serving which page, you'll have the search there also. To answer a question like "how is my sites rss.xml created?", a troubleshooting process may be:
   • Do a find-in-files for "rss.xml"
   • This returns, sure enough, a result in node.module : node_menu()
   • This tells us that the function in question - that serves that page - is node_feed(). This is where you want to look for further details.
10. All dynamic pages can be debugged by starting like this. Look at the URL, identify the module that serves that URL, trace the callback through the code.