transloadit/uppy · error · Error

Failed to create a session

Error message

Failed to create a session

What it means

Thrown when creating a Photos picking session fails: the POST to https://photospicker.googleapis.com/v1/sessions returned a non-OK status (after the UNAUTHENTICATED case was already handled as InvalidTokenError). It aborts showPhotosPicker before any UI polling starts, meaning the Google Photos Picker backend rejected session creation.

Source

Thrown at packages/@uppy/core/src/companion-client/googlePicker.ts:394

  // https://developers.google.com/photos/picker/guides/get-started-picker
  const headers = getAuthHeader(token)

  let newPickingSession = pickingSession
  if (newPickingSession == null) {
    const createSessionResponse = await fetch(
      'https://photospicker.googleapis.com/v1/sessions',
      { method: 'post', headers, signal },
    )

    if (createSessionResponse.status === 401) {
      const resp = await createSessionResponse.json()
      if (resp.error?.status === 'UNAUTHENTICATED') {
        throw new InvalidTokenError()
      }
    }

    if (!createSessionResponse.ok) {
      throw new Error('Failed to create a session')
    }
    newPickingSession = (await createSessionResponse.json()) as PickingSession

    onPickingSessionChange(newPickingSession)
  }

  const w = window.open(newPickingSession.pickerUri)
  signal?.addEventListener('abort', () => w?.close())
}

async function resolvePickedPhotos({
  accessToken,
  pickingSession,
  signal,
}: {
  accessToken: string
  pickingSession: PickingSession
  signal: AbortSignal

View on GitHub (pinned to 5d4dedd02a)

Solutions

1. Enable the 'Google Photos Picker API' in Google Cloud Console for the client ID's project
2. Ensure the access token is requested with the https://www.googleapis.com/auth/photospicker scope
3. Verify app verification status for Photos scopes (restricted scopes require Google review)
4. Retry — transient 5xx from the Picker backend resolves on its own

Example fix

// before
renderButton(uppy, { clientId: 'xxx' })
// -> Error: Failed to create a session (API not enabled)

// after
// Google Cloud Console -> APIs & Services -> enable 'Google Photos Picker API'
renderButton(uppy, { clientId: 'xxx' }) // works

// Pre-flight: confirm the Photos Picker API is enabled for this client
await fetch('https://photospicker.googleapis.com/v1/sessions', {
  method: 'POST', headers: { Authorization: `Bearer ${token}` },
}) // if 403 SERVICE_DISABLED, fix config before wiring the picker

null

try {
  await picker.showPicker()
} catch (err) {
  if (err.message === 'Failed to create a session') {
    uppy.info('Google Photos picking unavailable. Falling back to Drive picker.', 'warning', 5000)
  }
}

When it happens

Trigger: Calling the photos picker flow (showPhotosPicker) where the create-session request fails — invalid/expired token (non-UNAUTHENTICATED flavor), Photos Picker API not enabled, or a server-side 5xx.

Common situations: 'Google Photos Picker API' not enabled in the Google Cloud project; missing photospicker scope; app verification pending for sensitive Google Photos scopes; transient Google-side errors.

Related errors

• Failed to get a media items
• Failed to get session
• OAuth2 error: ${response.error}
• Failed to list folder contents for '${doc.name}' (${doc.id})
• Invalid request body

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