Drupal 6: Debugging form submissions

This post contains a few notes taken from a debugging session for a problem of the kind "submitted form is being returned to the sender without any error message" in a Drupal 6 installation. Furthermore, it contains some tips on debugging the "form values disappear into the void" symptom. These are surprisingly difficult issues to debug if you don't know where to start, as Drupal's control flow is notoriously convoluted due to indirection caused by hooks (as a matter of fact, quite a few software frameworks pay the same price for their flexibility) and because of generous use of recursion.

1. Check if form_set_error is called (with a non-empty argument) by any module during processing.
2. Instrument or break in function form_execute_handlers in form.inc. This is from where the validate and submit functions contributed by various modules are invoked from.
3. If the form validates, but an expected submit handler is not in the list, it may be due to the form id not matching the function name. If you cannot change either, you can still bring them together in the form_alter hook by appending to #submit, like so:

   $form['#submit'][] = 'user_register_submit';

4. If the form values in $form_state seem to be wrong or missing, debug the $form['#value'] assignments in _form_builder_handle_input_element (to conditionally break on a particular element, you can evaluate $form['#name']). In particular, for multistep forms pay attention to the #access attribute, which controls whether the values are populated from the form cache or from the POST request.