Why is form submit handler not called when calling form_set_error? I want to know where in Drupal documentation it is listed that submit handlers are not called when form_set_error has been called.

I don't see it in form_ser_error api, nor in FAPI Quickstart guide and FAPI reference.

Looks like I'm missing some simple thing.
submit handlers are only invoked if there are no validation errors. Calling form_set_error() results in a validation error.

From the quickstart guide that you linked:


1. A submit function is called only if a submit button was present and exists in the $_POST, and validation did not fail.