Error message presented when a BrokenPostRequestException is fired on AJAX submission can be misleading

Problem/Motivation

When an AJAX form is submitted, Drupal\Core\Form\FormBuilder::buildForm() performs the following check:

    // In case the post request exceeds the configured allowed size
    // (post_max_size), the post request is potentially broken. Add some
    // protection against that and at the same time have a nice error message.
    if ($ajax_form_request && !$request->request->has('form_id')) {
      throw new BrokenPostRequestException($this->getFileUploadMaxSize());
    }

This is intercepted by Drupal\Core\Form\EventSubscriber\FormAjaxSubscriber::onException() which has the following code:

    // Render a nice error message in case we have a file upload which exceeds
    // the configured upload limit.
    if ($exception instanceof BrokenPostRequestException && $request->query->has(FormBuilderInterface::AJAX_FORM_REQUEST)) {
      $this->messenger->addError($this->t('An unrecoverable error occurred. The uploaded file likely exceeded the maximum file size (@size) that this server supports.', ['@size' => $this->formatSize($exception->getSize())]));
      $response = new AjaxResponse(NULL, 200);
      $status_messages = ['#type' => 'status_messages'];
      $response->addCommand(new PrependCommand(NULL, $status_messages));
      $event->allowCustomResponseCode();
      $event->setResponse($response);
      return;
    }

Note that the exception is triggered by a missing form_id during an AJAX request.

There are multiple reasons I've discovered why form_id may be missing:

1. The request file size is too large and gets silently truncated (correctly called out in the existing error message)
2. A mistake in a form theme template causes the form_id to not get submitted.
3. The one that bit me: The number of form fields being submitted exceeds PHP's max_input_vars setting, which defaults to 1000.

Proposed resolution

The current error message is:

An unrecoverable error occurred. The uploaded file likely exceeded the maximum file size (@size) that this server supports.

We should replace this with a more descriptive and accurate message. Here is a proposed replacement:

An unrecoverable error occured. The form's form_id key must be present. Ensure your form is submitting it's form ID, that your form submission does not exceed the number of values set in PHP's max_input_vars (currently @amount), and the total size of your submission is less than the maximum file size (@size) that this server supports.

It's probably too verbose, so would love to see better proposals..

Remaining tasks

• Decide on a better error message.
• Implement it.

User interface changes

API changes

Data model changes

Release notes snippet