Yeah, the above example is not supposed to work.

Could you please open a feature request?

botum, thanks for sharing your findings.

I discovered another technique for displaying multiple error messages is to use form_set_error for the first message and drupal_set_message (with the second parameter set to 'error') for any additional messages. This won't solve the problem you're talking about though.

I'm pretty sure the above solution only works if the password fields are the only fields being passed into password_confirm_validate().

If you don't want to set the two, or more, comparative form elements under a common parent (looking at the code, this is what seems to make form_error() really work), I suggest setting the first element with form_set_error() as explained a bit further above, and then setting a flag value to rebuild the attributes of the other form elements.

Looking at the source code, I found that the error highlighting around form fields is turned on by adding the class 'error' to the form element.

So starting within your hook_validate function with form elements 'email' and 'confirm_email':

<?php
function myform_form_validate ($form, &$form_state) {
	$error = FALSE;
	// ...any other validation checks, making sure that $error is set to true if a validation check fails

	// If there are any previous validation errors, error message will exist -> set $error = TRUE
	$errors = form_get_errors();
	if (!empty($errors)) {
		$error = TRUE;
	}

	if ($form_state['values']['email'] != $form_state['values']['confirm_email']) {
		form_set_error('email', 'Email verification failed, please try again.');
		$form_state['rebuild'] = TRUE;
		$form_state['whitepaper']['confirm_email_error'] = TRUE;
	} else {
		if ($error) {
			$form_state['rebuild'] = TRUE;
		}
		$form_state['whitepaper']['confirm_email_error'] = FALSE;
	}
}
?>

The key above being setting $form_state['rebuild'] = TRUE, after setting your flag value to be 1. Also, we need another sentinel value $error to mark if there are any other errors in the validation process. Because $form_state['rebuild'] ignores any $form_state['redirect'] value, the $error needs to be turned on. That way if there are any previous failures in validation the form will rebuild itself, and re-present itself to the user. Otherwise, the form will proceed as expected.

Then in your hook_form:

<?php

function myform_form($form_state) {
	$form['name'] = array(
		'#type' => 'textfield',
		'#title' => t('Full Name'),
		'#required' => TRUE,
		'#default_value' => (isset($form_state['values']['name'])) ? $form_state['values']['name'] : '',
	);

	// ...additional form fields

	$form['email'] = array(
		'#type' => 'textfield',
		'#title' => t('Email Address'),
		'#required' => TRUE,
	);
	
	if (isset($form_state['mymodule']['confirm_email_error']) && $form_state['mymodule']['confirm_email_error'] === TRUE) {
		$attributes = array('class' => 'error');
	} else {
		$attributes = array();
	}
	
	$form['confirm_email'] = array(
		'#type' => 'textfield',
		'#title' => t('Confirm Email'),
		'#required' => TRUE,
		'#attributes' => $attributes,
	);
	
	// ... any other fields
	
	return $form;
}
?>

Setting $form_state['rebuild'] = TRUE will allow you to reset the attributes after validation. For additional form fields, just set '#atttributes' => $attributes.

I included the form element 'name' to illustrate that any values that you want repopulated when the form rebuilds, you have to use the '#default_value' property for the form element, otherwise the value is not populated.

Not all pretty, but does work.

The array_pop method would remove other error messages, so that can't be assumed "safe".

The message above about setting #parent would certainly work, but you'd set errors on every child, even those that contain data and are already correct.

I think the best thing to do is run <?php $_SESSION['messages']['error'] = array_unique($_SESSION['messages']['error']); ?> at the end of your _form_validate() function after setting errors on everything that's an error.

Edit: Well, you'd really want to make sure the ['error'] array exists before setting it, otherwise you'll print errors even when there are none!

<?php
// Remove duplicate messages.
if (isset($_SESSION['messages']['error'])) {
  $_SESSION['messages']['error'] = array_unique($_SESSION['messages']['error']);
}
?>

The following code is showing error message only once but highlighting in red three fields:

        form_set_error('cities',t("You can select maximum of $MAX_SELECTIONS choices!"));
        form_set_error('states','');
        form_set_error('societies','');