transloadit/uppy · error · Error

Unexpected Facebook response: missing images

Error message

Unexpected Facebook response: missing images

What it means

After fetching a Facebook photo's metadata, Companion filters the body.images array for valid image objects (with a numeric height/width and string source), sorts them, and returns the largest one's URL. If none survive filtering, this error is thrown.

Source

Thrown at packages/@uppy/companion/src/server/provider/facebook/index.ts:111

  const first = batch[0]
  if (!first) throw new Error('Unexpected Facebook response: missing body')
  const body = first.body

  const imagesValue = isRecord(body) ? body['images'] : undefined

  const isFbImage = (
    value: unknown,
  ): value is { width: number; source: string } =>
    isRecord(value) &&
    typeof value['width'] === 'number' &&
    typeof value['source'] === 'string'

  const images = Array.isArray(imagesValue) ? imagesValue.filter(isFbImage) : []
  const sortedImages = sortImages(images)
  const largest = sortedImages[sortedImages.length - 1]
  if (!largest) {
    throw new Error('Unexpected Facebook response: missing images')
  }
  return largest.source
}

/**
 * Adapter for API https://developers.facebook.com/docs/graph-api/using-graph-api/
 */
export default class Facebook extends Provider<FacebookUserSession> {
  static override get oauthProvider() {
    return 'facebook'
  }

  override async list({
    directory,
    providerUserSession: { accessToken: token },
    query,
    companion,
  }: {

View on GitHub (pinned to 5d4dedd02a)

Solutions

1. Verify the requested id is a photo (not a video/album) — videos go through a different download path
2. Re-authenticate to ensure full photo fields are returned
3. Log and inspect the raw Graph API response for that id (add fields=images to a Graph API explorer query)
4. If Facebook changed the schema, pin/upgrade Companion to a version tracking the current Graph API

function isFbImageResponse(body: unknown): body is { images: { source: string }[] } {
  return (
    typeof body === 'object' && body !== null &&
    Array.isArray((body as any).images) &&
    (body as any).images.some((i: any) => typeof i?.source === 'string')
  )
}

try {
  const url = await getMediaUrl({ secret, token, id })
} catch (err) {
  if (err instanceof Error && err.message.includes('missing images')) {
    return userMessage('No downloadable image found for this item.')
  }
  throw err
}

When it happens

Trigger: The Facebook response's images field is missing, empty, or contains only entries that fail the isFbImage check (non-string source or non-numeric dimensions) when downloading a Facebook photo via getMediaUrl.

Common situations: Facebook changed its response shape for photo objects, the item is a video or album cover with no downloadable images array, or partial/permission-restricted responses return stripped fields.

Related errors

• Unexpected Facebook response: missing body
• Unexpected Facebook response: missing batch result
• Facebook provider secret is not configured
• call to thumbnail is not implemented
• File data is missing for file ${options.file.id}

AI-assisted analysis of transloadit/uppy@5d4dedd02a (2026-08-28). Data as JSON: /api/errors/27d79c50d7afed6f. Report an issue: GitHub.