The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.
TypeScript aialternativeauthdatabasedenoembeddingsexamplefirebasenextjsoauth2pgvectorpostgispostgrespostgresqlpostgrestrealtimesupabasevectorswebsockets
feat(telemetry): classify funnel creation errors (#47293)
Pamela Chia2d0bcd4714af
diff --git a/apps/studio/components/interfaces/Organization/NewOrg/NewOrgForm.tsx b/apps/studio/components/interfaces/Organization/NewOrg/NewOrgForm.tsxindex a7c147df6d1..c21083f1d1f 100644--- a/apps/studio/components/interfaces/Organization/NewOrg/NewOrgForm.tsx+++ b/apps/studio/components/interfaces/Organization/NewOrg/NewOrgForm.tsx@@ -58,6 +58,12 @@ import { useLastVisitedOrganization } from '@/hooks/misc/useLastVisitedOrganizatimport { PRICING_TIER_LABELS_ORG, STRIPE_PUBLIC_KEY } from '@/lib/constants'import { validateReturnTo } from '@/lib/gotrue'import { useProfile } from '@/lib/profile'+import {+ classifyApiError,+ classifyStripeError,+ classifyValidationError,+} from '@/lib/telemetry/funnel-errors'+import { useTrackFunnelError } from '@/lib/telemetry/use-track-funnel-error'interface NewOrgFormProps {onPaymentMethodReset: () => void@@ -226,6 +232,8 @@ export const NewOrgForm = ({[freeOrgs, projectsByOrg])+ const trackFunnelError = useTrackFunnelError()+const { mutate: createOrganization } = useOrganizationCreateMutation({onSuccess: async (org) => {if ('pending_payment_intent_secret' in org && org.pending_payment_intent_secret) {@@ -236,6 +244,7 @@ export const NewOrgForm = ({},onError: (data) => {toast.error(data.message, { duration: 10_000 })+ trackFunnelError('org_creation', classifyApiError('org_creation', data), 'toast')setNewOrgLoading(false)},})@@ -246,6 +255,10 @@ export const NewOrgForm = ({onOrganizationCreated({ slug: data.slug })}},+ onError: (error) => {+ toast.error(error.message, { dismissible: true, duration: 10_000 })+ trackFunnelError('org_creation', classifyApiError('org_creation', error), 'toast')+ },})const paymentIntentConfirmed = async (paymentIntentConfirmation: PaymentIntentResult) => {@@ -260,6 +273,11 @@ export const NewOrgForm = ({size: form.getValues('size'),})} else {+ trackFunnelError(+ 'org_creation',+ classifyStripeError(paymentIntentConfirmation.error),+ 'toast'+ )// If the payment intent is not successful, we reset the payment method and show an errortoast.error(`Could not confirm payment. Please try again or use a different card.`, {duration: 10_000,@@ -354,7 +372,12 @@ export const NewOrgForm = ({return (<Form {...form}>- <form onSubmit={form.handleSubmit(onSubmit)} id={FORM_ID}>+ <form+ onSubmit={form.handleSubmit(onSubmit, (errors) =>+ trackFunnelError('org_creation', classifyValidationError('org_creation', errors), 'form')+ )}+ id={FORM_ID}+ ><Paneltitle={<div key="panel-title">@@ -547,6 +570,11 @@ export const NewOrgForm = ({onLoadingChange={(loading) => setPaymentConfirmationLoading(loading)}onError={(err) => {toast.error(err.message, { duration: 10_000 })+ trackFunnelError(+ 'org_creation',+ { errorCategory: 'payment', errorReason: 'payment_error' },+ 'toast'+ )setNewOrgLoading(false)resetPaymentMethod()}}diff --git a/apps/studio/components/interfaces/SignIn/SignUpForm.tsx b/apps/studio/components/interfaces/SignIn/SignUpForm.tsxindex f1bcacd97aa..e3c6c3f2490 100644--- a/apps/studio/components/interfaces/SignIn/SignUpForm.tsx+++ b/apps/studio/components/interfaces/SignIn/SignUpForm.tsx@@ -25,6 +25,8 @@ import PasswordConditionsHelper from './PasswordConditionsHelper'import { useSignUpMutation } from '@/data/misc/signup-mutation'import { BASE_PATH } from '@/lib/constants'import { buildPathWithParams } from '@/lib/gotrue'+import { classifyApiError, classifyValidationError } from '@/lib/telemetry/funnel-errors'+import { useTrackFunnelError } from '@/lib/telemetry/use-track-funnel-error'const schema = z.object({email: z.string().min(1, 'Email is required').email('Must be a valid email'),@@ -67,6 +69,8 @@ export const SignUpForm = () => {token: parseAsString.withDefault(''),})+ const trackFunnelError = useTrackFunnelError()+const { mutate: signup, isPending: isSigningUp } = useSignUpMutation({onSuccess: () => {toast.success(`Signed up successfully!`)@@ -76,6 +80,7 @@ export const SignUpForm = () => {setCaptchaToken(null)captchaRef.current?.resetCaptcha()toast.error(`Failed to sign up: ${error.message}`)+ trackFunnelError('signup', classifyApiError('signup', error), 'toast')},})@@ -144,7 +149,13 @@ export const SignUpForm = () => {)}><Form {...form}>- <form id={formId} className="flex flex-col gap-4" onSubmit={form.handleSubmit(onSubmit)}>+ <form+ id={formId}+ className="flex flex-col gap-4"+ onSubmit={form.handleSubmit(onSubmit, (errors) =>+ trackFunnelError('signup', classifyValidationError('signup', errors), 'form')+ )}+ ><FormFieldkey="email"name="email"diff --git a/apps/studio/lib/telemetry/funnel-errors.test.ts b/apps/studio/lib/telemetry/funnel-errors.test.tsnew file mode 100644index 00000000000..6abe0049b6d--- /dev/null+++ b/apps/studio/lib/telemetry/funnel-errors.test.ts@@ -0,0 +1,114 @@+import type { FieldErrors } from 'react-hook-form'+import { describe, expect, it } from 'vitest'++import { classifyApiError, classifyStripeError, classifyValidationError } from './funnel-errors'++describe('classifyApiError', () => {+ it('classifies connection timeout as network', () => {+ expect(classifyApiError('signup', { errorType: 'connection-timeout' })).toEqual({+ errorCategory: 'network',+ errorReason: 'connection_timeout',+ })+ })++ it('classifies a missing status code as network_error', () => {+ expect(classifyApiError('project_creation', { message: 'Failed to fetch' })).toEqual({+ errorCategory: 'network',+ errorReason: 'network_error',+ })+ })++ it('classifies 429 as rate_limited regardless of message', () => {+ expect(classifyApiError('signup', { code: 429, message: 'whatever' })).toEqual({+ errorCategory: 'api',+ errorReason: 'rate_limited',+ errorCode: 429,+ })+ })++ it('classifies 5xx as server_error', () => {+ expect(classifyApiError('org_creation', { code: 500, message: 'boom' })).toEqual({+ errorCategory: 'api',+ errorReason: 'server_error',+ errorCode: 500,+ })+ })++ it('matches a known 4xx signup message to a reason slug', () => {+ expect(classifyApiError('signup', { code: 400, message: 'User already registered' })).toEqual({+ errorCategory: 'api',+ errorReason: 'email_already_registered',+ errorCode: 400,+ })+ })++ it('matches a known 4xx project message to a reason slug', () => {+ expect(+ classifyApiError('project_creation', {+ code: 403,+ message: 'Your organization can only have 2 projects',+ })+ ).toEqual({ errorCategory: 'api', errorReason: 'project_limit_reached', errorCode: 403 })+ })++ it('falls back to other for an unmapped 4xx message', () => {+ expect(classifyApiError('signup', { code: 400, message: 'totally novel error' })).toEqual({+ errorCategory: 'api',+ errorReason: 'other',+ errorCode: 400,+ })+ })+})++describe('classifyValidationError', () => {+ it('maps a signup password error to password_invalid', () => {+ expect(+ classifyValidationError('signup', { password: { type: 'too_small' } } as FieldErrors)+ ).toEqual({+ errorCategory: 'validation',+ errorReason: 'password_invalid',+ })+ })++ it('respects field priority (email before password)', () => {+ expect(+ classifyValidationError('signup', {+ email: { type: 'invalid' },+ password: { type: 'too_small' },+ } as FieldErrors)+ ).toEqual({ errorCategory: 'validation', errorReason: 'email_invalid' })+ })++ it('maps an org name error to org_name_missing', () => {+ expect(+ classifyValidationError('org_creation', { name: { type: 'too_small' } } as FieldErrors)+ ).toEqual({+ errorCategory: 'validation',+ errorReason: 'org_name_missing',+ })+ })++ it('falls back to other for an unmapped field', () => {+ expect(+ classifyValidationError('project_creation', { somethingNew: { type: 'x' } } as FieldErrors)+ ).toEqual({ errorCategory: 'validation', errorReason: 'other' })+ })+})++describe('classifyStripeError', () => {+ it('maps a decline_code to a card reason slug', () => {+ expect(+ classifyStripeError({ code: 'card_declined', decline_code: 'insufficient_funds' })+ ).toEqual({+ errorCategory: 'payment',+ errorReason: 'card_insufficient_funds',+ })+ })++ it('falls back to payment_failed for an unknown code', () => {+ expect(classifyStripeError({ code: 'mystery' })).toEqual({+ errorCategory: 'payment',+ errorReason: 'payment_failed',+ })+ })+})diff --git a/apps/studio/lib/telemetry/funnel-errors.ts b/apps/studio/lib/telemetry/funnel-errors.tsnew file mode 100644index 00000000000..579d0cc6bea--- /dev/null+++ b/apps/studio/lib/telemetry/funnel-errors.ts@@ -0,0 +1,142 @@+import type { FieldErrors } from 'react-hook-form'++export type FunnelOrigin = 'signup' | 'project_creation' | 'org_creation'+export type ErrorCategory = 'validation' | 'api' | 'network' | 'payment' | 'unknown'++export interface FunnelErrorClassification {+ errorCategory: ErrorCategory+ errorReason: FunnelErrorReason+ errorCode?: number+}++const RATE_LIMIT_STATUS = 429++const API_REASON_PATTERNS = {+ signup: [+ [/already registered|already been registered|already exists/i, 'email_already_registered'],+ [/rate limit|too many requests|after \d+ second/i, 'rate_limited'],+ [/captcha/i, 'captcha_failed'],+ [/password/i, 'password_rejected'],+ [/valid email|invalid email|email address/i, 'email_invalid'],+ ],+ project_creation: [+ [/already exists/i, 'project_name_taken'],+ [/free plan|free tier/i, 'free_tier_limit'],+ [/limit|maximum number|can only have/i, 'project_limit_reached'],+ [/payment|invoice|overdue|past due|billing/i, 'billing_issue'],+ [/region/i, 'region_unavailable'],+ [/db_pass|password/i, 'db_password_rejected'],+ ],+ org_creation: [+ [/already exists|name.*taken/i, 'org_name_taken'],+ [/payment|card|invoice|billing/i, 'billing_issue'],+ [/limit/i, 'org_limit_reached'],+ ],+} as const satisfies Record<FunnelOrigin, ReadonlyArray<readonly [RegExp, string]>>++const VALIDATION_FIELD_REASONS = {+ signup: {+ email: 'email_invalid',+ password: 'password_invalid',+ },+ project_creation: {+ organization: 'organization_missing',+ projectName: 'project_name_invalid',+ dbPass: 'db_password_weak',+ dbPassStrength: 'db_password_weak',+ dbRegion: 'region_missing',+ cloudProvider: 'cloud_provider_invalid',+ postgresVersion: 'postgres_version_missing',+ highAvailability: 'incompatible_options',+ useOrioleDb: 'incompatible_options',+ },+ org_creation: {+ name: 'org_name_missing',+ kind: 'org_kind_invalid',+ size: 'org_size_invalid',+ },+} as const satisfies Record<FunnelOrigin, Readonly<Record<string, string>>>++const STRIPE_DECLINE_REASONS = {+ insufficient_funds: 'card_insufficient_funds',+ card_declined: 'card_declined',+ expired_card: 'card_expired',+ incorrect_cvc: 'card_incorrect_cvc',+ incorrect_number: 'card_incorrect_number',+ processing_error: 'card_processing_error',+} as const satisfies Record<string, string>++const GENERIC_REASONS = [+ 'rate_limited',+ 'server_error',+ 'connection_timeout',+ 'network_error',+ 'payment_failed',+ 'payment_error',+ 'oriole_unavailable',+ 'other',+] as const++type ValuesOf<T> = T extends Readonly<Record<string, infer V extends string>> ? V : never++export type FunnelErrorReason =+ | (typeof API_REASON_PATTERNS)[FunnelOrigin][number][1]+ | ValuesOf<(typeof VALIDATION_FIELD_REASONS)[FunnelOrigin]>+ | ValuesOf<typeof STRIPE_DECLINE_REASONS>+ | (typeof GENERIC_REASONS)[number]++export function classifyApiError(origin: FunnelOrigin, error: unknown): FunnelErrorClassification {+ const err = error as { code?: unknown; errorType?: unknown; message?: unknown }+ const code = typeof err?.code === 'number' ? err.code : undefined+ const message = typeof err?.message === 'string' ? err.message : ''++ if (err?.errorType === 'connection-timeout') {+ return { errorCategory: 'network', errorReason: 'connection_timeout' }+ }+ if (code === undefined) {+ return { errorCategory: 'network', errorReason: 'network_error' }+ }+ if (code === RATE_LIMIT_STATUS) {+ return { errorCategory: 'api', errorReason: 'rate_limited', errorCode: code }+ }+ if (code >= 500) {+ return { errorCategory: 'api', errorReason: 'server_error', errorCode: code }+ }+ for (const [pattern, reason] of API_REASON_PATTERNS[origin]) {+ if (pattern.test(message)) {+ return { errorCategory: 'api', errorReason: reason, errorCode: code }+ }+ }+ return { errorCategory: 'api', errorReason: 'other', errorCode: code }+}++export function classifyValidationError(+ origin: FunnelOrigin,+ errors: FieldErrors+): FunnelErrorClassification {+ const fieldErrors = errors as Record<string, unknown>+ const reasons = VALIDATION_FIELD_REASONS[origin] as Readonly<Record<string, FunnelErrorReason>>+ for (const field of Object.keys(reasons)) {+ if (fieldErrors[field]) {+ return { errorCategory: 'validation', errorReason: reasons[field] }+ }+ }+ return { errorCategory: 'validation', errorReason: 'other' }+}++export function classifyStripeError(error: unknown): FunnelErrorClassification {+ const err = error as { code?: unknown; decline_code?: unknown }+ const key =+ typeof err?.decline_code === 'string'+ ? err.decline_code+ : typeof err?.code === 'string'+ ? err.code+ : undefined+ const reason = key+ ? (STRIPE_DECLINE_REASONS as Readonly<Record<string, FunnelErrorReason>>)[key]+ : undefined+ if (reason) {+ return { errorCategory: 'payment', errorReason: reason }+ }+ return { errorCategory: 'payment', errorReason: 'payment_failed' }+}diff --git a/apps/studio/lib/telemetry/use-track-funnel-error.ts b/apps/studio/lib/telemetry/use-track-funnel-error.tsnew file mode 100644index 00000000000..3aa00091a55--- /dev/null+++ b/apps/studio/lib/telemetry/use-track-funnel-error.ts@@ -0,0 +1,28 @@+import { useCallback } from 'react'++import type { FunnelErrorClassification, FunnelOrigin } from '@/lib/telemetry/funnel-errors'+import { useTrack } from '@/lib/telemetry/track'++// Matches the existing dashboard_error_created capture rate; keeps PostHog volume bounded.+const SAMPLE_RATE = 0.1++export function useTrackFunnelError() {+ const track = useTrack()+ return useCallback(+ (+ origin: FunnelOrigin,+ classification: FunnelErrorClassification,+ source: 'toast' | 'form' = 'toast'+ ) => {+ if (Math.random() >= SAMPLE_RATE) return+ track('dashboard_error_created', {+ source,+ origin,+ errorCategory: classification.errorCategory,+ errorReason: classification.errorReason,+ ...(classification.errorCode !== undefined && { errorCode: classification.errorCode }),+ })+ },+ [track]+ )+}diff --git a/apps/studio/pages/new/[slug].tsx b/apps/studio/pages/new/[slug].tsxindex a01856a6536..a1738298df2 100644--- a/apps/studio/pages/new/[slug].tsx+++ b/apps/studio/pages/new/[slug].tsx@@ -71,13 +71,16 @@ import { usePHFlag } from '@/hooks/ui/useFlag'import { DOCS_URL, PROJECT_STATUS, PROVIDERS, useDefaultProvider } from '@/lib/constants'import { buildStudioPageTitle } from '@/lib/page-title'import { useProfile } from '@/lib/profile'+import { classifyApiError, classifyValidationError } from '@/lib/telemetry/funnel-errors'import { useTrack } from '@/lib/telemetry/track'+import { useTrackFunnelError } from '@/lib/telemetry/use-track-funnel-error'import type { NextPageWithLayout } from '@/types'const sizesWithNoCostConfirmationRequired: DesiredInstanceSize[] = ['micro', 'small']const Wizard: NextPageWithLayout = () => {const track = useTrack()+ const trackFunnelError = useTrackFunnelError()const router = useRouter()const { slug, projectName } = useParams()const { appTitle } = useCustomContent(['app:title'])@@ -317,6 +320,10 @@ const Wizard: NextPageWithLayout = () => {)router.push(`/project/${res.ref}`)},+ onError: (error) => {+ toast.error(`Failed to create new project: ${error.message}`)+ trackFunnelError('project_creation', classifyApiError('project_creation', error), 'toast')+ },})const onSubmitWithComputeCostsConfirmation = async (values: z.infer<typeof FormSchema>) => {@@ -356,6 +363,11 @@ const Wizard: NextPageWithLayout = () => {} = valuesif (useOrioleDb && !availableOrioleVersion) {+ trackFunnelError(+ 'project_creation',+ { errorCategory: 'validation', errorReason: 'oriole_unavailable' },+ 'toast'+ )return toast.error('No available OrioleDB image found, only Postgres is available')}@@ -501,7 +513,15 @@ const Wizard: NextPageWithLayout = () => {<meta name="description" content="Supabase Studio" /></Head><Form {...form}>- <form onSubmit={form.handleSubmit(onSubmitWithComputeCostsConfirmation)}>+ <form+ onSubmit={form.handleSubmit(onSubmitWithComputeCostsConfirmation, (errors) =>+ trackFunnelError(+ 'project_creation',+ classifyValidationError('project_creation', errors),+ 'form'+ )+ )}+ ><Panelloading={!isOrganizationsSuccess}title={diff --git a/packages/common/telemetry-constants.ts b/packages/common/telemetry-constants.tsindex 3fee50a2d4a..b72164ac2cb 100644--- a/packages/common/telemetry-constants.ts+++ b/packages/common/telemetry-constants.ts@@ -2842,7 +2842,7 @@ export interface DashboardErrorCreatedEvent {/*** Source of the error*/- source?: 'admonition' | 'toast' | 'error_display'+ source?: 'admonition' | 'toast' | 'error_display' | 'form'/*** Type of error matched (for error_display source)*/@@ -2851,6 +2851,22 @@ export interface DashboardErrorCreatedEvent {* Whether troubleshooting steps are available (for error_display source)*/hasTroubleshooting?: boolean+ /**+ * Funnel the error occurred in (set only for instrumented funnel errors)+ */+ origin?: 'signup' | 'project_creation' | 'org_creation'+ /**+ * Coarse classification of the funnel error+ */+ errorCategory?: 'validation' | 'api' | 'network' | 'payment' | 'unknown'+ /**+ * Controlled-vocabulary slug describing the reason (no free text, no PII)+ */+ errorReason?: string+ /**+ * HTTP status code for api/network errors (absent for validation/payment)+ */+ errorCode?: number}groups: TelemetryGroups}