Issue with upload file using Payload CMS REST API

[mrwebninja]

Describe the Bug

I am working with playload cms & trying to create a doc in collection with a file, following this payload documentation article https://payloadcms.com/docs/upload/overview#uploading-files

Collection config code

import type { CollectionConfig } from 'payload'
export const DemoCollection: CollectionConfig = {
  slug: 'demoCollection',
  fields: [
    {
      type: 'text',
      name: 'title',
      label: 'Title',
    },
    { type: 'upload', name: 'image', label: 'Image', relationTo: 'media' },
  ],
}

upload Page using REST API

'use client'
const FormSchema = z.object({
  title: z.string().min(2, {
    message: 'Title must be at least 2 characters.',
  }),
  image: z.instanceof(FileList),
})
const DemoPage = () => {
  const form = useForm<z.infer<typeof FormSchema>>({
    resolver: zodResolver(FormSchema),
    defaultValues: {
      title: '',
    },
  })
  async function onSubmit(data: z.infer<typeof FormSchema>) {
    const formData = new FormData()
      formData.append('image', data.image[0])
    formData.append('title', data.title)
    console.log('formData', formData)
    try {
      const req = await fetch('{apiurl}/demoCollection', {
        method: 'POST',
        credentials: 'include',
        body: formData,
      })
      const data = await req.json()
      console.log('res data', data)
    } catch (err) {
      console.log(err)
    }
  }
  return (
    <div className="container">
      <Form {...form}>
        <form onSubmit={form.handleSubmit(onSubmit)} className="w-2/3 space-y-6">
          <FormField
            control={form.control}
            name="title"
            render={({ field }) => (
              <FormItem>
                <FormLabel>Title</FormLabel>
                <FormControl>
                  <Input placeholder="Enter title" {...field} />
                </FormControl>
                <FormDescription>This is the title of your demo item.</FormDescription>
                <FormMessage />
              </FormItem>
            )}
          />
          <FormField
            control={form.control}
            name="image"
            render={({ field }) => (
              <FormItem>
                <FormControl>
                  <Input
                    type="file"
                    onChange={(e) => {
                      field.onChange(e.target.files)
                    }}
                  />
                </FormControl>
                <FormDescription>Upload your image file.</FormDescription>
                <FormMessage />
              </FormItem>
            )}
          />
          <Button type="submit">Submit</Button>
        </form>
      </Form>
    </div>
  )
}
export default DemoPage

error on browser
Something went wrong.

error on the server console

Cannot read properties of undefined (reading 'title')

Thanks in advance for your help

Link to the code that reproduces this issue

https://github.com/payloadcms/payload/tree/main/templates/website

Reproduction Steps

I also try with include headers
headers: {

• 'Content-Type': 'multipart/form-data'
  *}

Which area(s) are affected? (Select all that apply)

Not sure

Environment Info

Node: 22.14.0
Relevant Packages:
  payload: 3.28.1
  next: 15.2.0
  @payloadcms/db-mongodb: 3.25.0
  @payloadcms/email-nodemailer: 3.27.0
  @payloadcms/email-resend: 3.25.0
  @payloadcms/graphql: 3.27.0
  @payloadcms/live-preview: 3.27.0
  @payloadcms/live-preview-react: 3.25.0
  @payloadcms/next/utilities: 3.25.0
  @payloadcms/payload-cloud: 3.25.0
  @payloadcms/plugin-form-builder: 3.25.0
  @payloadcms/plugin-nested-docs: 3.25.0
  @payloadcms/plugin-redirects: 3.25.0
  @payloadcms/plugin-search: 3.25.0
  @payloadcms/plugin-seo: 3.25.0
  @payloadcms/richtext-lexical: 3.25.0
  @payloadcms/translations: 3.27.0
  @payloadcms/ui/shared: 3.25.0
  react: 19.0.0
  react-dom: 19.0.0

[akhrarovsaid]

Hey @mrwebninja

Try this:

const formData = new FormData()
formData.append('image', data.image[0])
formData.append('_payload', JSON.stringify({ title: data.title }))

The API is expecting extra fields under the '_payload' key which is what seems to be missing from your example here, so I think the above should work for you here. Maybe the docs could be more clear on this with more examples as it is not an uncommon question.

[PatrikKozak]

Hey @mrwebninja - any chance you were able to try out @akhrarovsaid 's suggestion?

Happy to dive deeper into this if you're still experiencing your issue even after trying the above.

[j-mir-prazak]

Hi,
I noticed this few weeks before and was able to trace the "_payload" field from DevTools. I am working on some fileuploads today again and realized that I did not make an issue that this is missing in docs.

I have new and latest stable project, so it is still not changed so far - I guest that the docs should include this part:

To upload a file, use your collection's create endpoint. Send it all the data that your Collection requires, as well as a file key containing the file that you'd like to upload.

should mention that you have to stringify the data and append it to _payload field

[PatrikKozak]

Hey @mrwebninja, @akhrarovsaid & @j-mir-prazak - I just opened a PR that will add some clarity into the docs for the above issue.

Thanks for bringing this up!

Will close this once the doc updates are merged.

[github-actions]

🚀 This is included in version v3.34.0