supabase/supabase · error · Error

projectRef is required

Error message

projectRef is required

What it means

Thrown by getProjectStorageConfig (apps/studio/data/config/project-storage-config-query.ts:20) before GET /platform/projects/{ref}/config/storage. Beyond the standard missing-ref guard, this fetcher also patches a known API gap: a 404 with no message is rewritten to 'Storage configuration not found.' before handleError. The ref guard fires first, so the 404 patch only runs once a ref is present.

Source

Thrown at apps/studio/data/config/project-storage-config-query.ts:20

import { configKeys } from './keys'
import { components } from '@/data/api'
import { get, handleError } from '@/data/fetchers'
import { useDeploymentMode } from '@/hooks/misc/useDeploymentMode'
import { IS_PLATFORM } from '@/lib/constants'
import type { ResponseError, UseCustomQueryOptions } from '@/types'

export type ProjectStorageConfigVariables = {
  projectRef?: string
}

export type ProjectStorageConfigResponse = components['schemas']['StorageConfigResponse']

export async function getProjectStorageConfig(
  { projectRef }: ProjectStorageConfigVariables,
  signal?: AbortSignal
) {
  if (!projectRef) throw new Error('projectRef is required')

  const { data, error } = await get('/platform/projects/{ref}/config/storage', {
    params: { path: { ref: projectRef } },
    signal,
  })

  if (error) {
    // [Joshen] This is due to API not returning an error message on this endpoint if a 404 is returned
    // Should only be a temporary patch, needs to be addressed on the API end
    if ((error as any).code === 404) {
      handleError({ ...(error as any), message: 'Storage configuration not found.' })
    } else {
      handleError(error)
    }
  }
  return data
}

View on GitHub (pinned to beee91b9c2)

Solutions

1. Gate the hook with enabled: typeof projectRef === 'string'.
2. Handle the downstream 404 ('Storage configuration not found.') as an empty state rather than an error, since it often means 'not provisioned yet'.
3. For direct calls, early-return when projectRef is falsy.

Example fix

// before
const { data } = await getProjectStorageConfig({ projectRef })

// after
if (!projectRef) return null
const { data } = await getProjectStorageConfig({ projectRef })

if (!projectRef) return null
await getProjectStorageConfig({ projectRef })

const hasProjectRef = (
  v: { projectRef?: string }
): v is { projectRef: string } => typeof v.projectRef === 'string' && v.projectRef.length > 0

if (!hasProjectRef(vars)) return null
try {
  return await getProjectStorageConfig(vars)
} catch (e) {
  // a 404 here means storage not provisioned yet — treat as empty state
  return null
}

When it happens

Trigger: Opening the Storage config settings before projectRef resolves, or on a project whose storage backend has not been provisioned (which then surfaces the 404 message, not this guard).

Common situations: Newly created project where storage config is not yet available, or a settings tab mounted during project bootstrap before the ref is set.

Related errors

• Project ref is required
• projectRef is required
• Project ref is required
• projectRef is required
• projectRef is required

AI-assisted analysis of supabase/supabase@beee91b9c2 (2026-08-12). Data as JSON: /api/errors/f2fa41da9f0757b8. Report an issue: GitHub.