Why is my file upload always NULL in $form_state? I've build a form where the user can upload an image as avatar for his profile. But I have an issue as the selected image is not being recognized at all.

I used the image example from drupal.org, this is my minimal code not working at all: 

function my_edit_form($form, $form_state, $entity) {

  $form['picture']['picture_upload'] = array(
    '#type' =&gt; 'file',
    '#title' =&gt; t("Upload picture"),
    '#description' =&gt; t("Your virtual face or picture. Pictures larger than 150x150 pixels will be scaled down."),
    '#upload_location' =&gt; 'public://pictures/',
    '#size' =&gt; 48,
  );

  return $form;
}




Now, I'm trying to use the file() functions as described in the documentation but it seems my $form_state['values']['picture'] is always NULL.

function my_edit_form_submit($form, &amp;$form_state) {
  dpm($form_state);
}




I have no idea how that's possible and I'm a bit lost here. Any idea what else I could try?
Okay, this is tricky how Drupal handles the file uploads and took me some time to figure out.

$form_state indeed shows NULL or empty strings or empty arrays for my file upload unless I add a proper upload function. The file exists but is not uploaded yet.

It's worth taking a look at user_validate_picture():

function user_validate_picture(&amp;$form, &amp;$form_state) {
  // If required, validate the uploaded picture.
  $validators = array(
    'file_validate_is_image' =&gt; array(),
    'file_validate_image_resolution' =&gt; array(variable_get('user_picture_dimensions', '85x85')),
    'file_validate_size' =&gt; array(variable_get('user_picture_file_size', '30') * 1024),
  );

  // Save the file as a temporary file.
  $file = file_save_upload('picture_upload', $validators);
  if ($file === FALSE) {
    form_set_error('picture_upload', t("Failed to upload the picture image; the %directory directory doesn't exist or is not writable.", array('%directory' =&gt; variable_get('user_picture_path', 'pictures'))));
  }
  elseif ($file !== NULL) {
    $form_state['values']['picture_upload'] = $file;
  }
}


Calling this function from inside my own validation function will upload the file to temporary://What-is-Sustainability_0.png and it's now visible in $form_state['values']:



This is what I was looking for, now I can simply save the file where I need it and have the fid available to link it to entities.