supabase/supabase · error · Error

projectRef is required

Error message

projectRef is required

What it means

Thrown by getNetworkRestrictions when projectRef is missing. The function GETs /v1/projects/{ref}/network-restrictions and the path param is the project's ref string; an empty ref would either 404 or hit the wrong project, so the guard refuses to call the API.

Source

Thrown at apps/studio/data/network-restrictions/network-restrictions-query.ts:21

import { networkRestrictionKeys } from './keys'
import { get, handleError } from '@/data/fetchers'
import { UseCustomQueryOptions } from '@/types'

export type NetworkRestrictionsVariables = { projectRef?: string }

export type NetworkRestrictionsResponse = {
  entitlement: 'disallowed' | 'allowed'
  status: '' | 'stored' | 'applied'
  config: { dbAllowedCidrs: string[] }
  old_config?: { dbAllowedCidrs: string[] }
  error?: any
}

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

  const { data, error } = await get('/v1/projects/{ref}/network-restrictions', {
    params: { path: { ref: projectRef } },
    signal,
  })

  // Not allowed error is a valid response to denote if a project
  // has access to the network restrictions UI, so we'll handle it here
  if (error) {
    const isNotAllowedError =
      (error as any)?.code === 400 &&
      (error as any)?.message?.includes('not allowed to set up network restrictions')

    if (isNotAllowedError) {
      return {
        entitlement: 'disallowed',
        config: { dbAllowedCidrs: [] },
        status: '',

View on GitHub (pinned to beee91b9c2)

Solutions

1. Gate the query: enabled: !!projectRef on the useQuery options.
2. Pull projectRef from the project store / useParams and only render the NetworkRestrictions UI when it is truthy.
3. In tests, pass a fixed projectRef via the query hook's variables.

Example fix

// before
export const useNetworkRestrictionsQuery = ({ projectRef }) =>
  useQuery({
    queryKey: networkRestrictionKeys.list(projectRef),
    queryFn: ({ signal }) => getNetworkRestrictions({ projectRef }, signal),
  })

// after
export const useNetworkRestrictionsQuery = ({ projectRef }) =>
  useQuery({
    queryKey: networkRestrictionKeys.list(projectRef),
    enabled: Boolean(projectRef),
    queryFn: ({ signal }) => getNetworkRestrictions({ projectRef: projectRef! }, signal),
  })

// gate the React Query so the fetcher never runs without a ref
export const useNetworkRestrictionsQuery = ({ projectRef }: { projectRef?: string }) =>
  useQuery({
    queryKey: networkRestrictionKeys.list(projectRef),
    enabled: Boolean(projectRef),
    queryFn: ({ signal }) => getNetworkRestrictions({ projectRef: projectRef! }, signal),
  })

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

const { error } = useNetworkRestrictionsQuery({ projectRef })

if (error instanceof Error && error.message === 'projectRef is required') {
  // project context not loaded yet; render a skeleton, do not refetch
}

When it happens

Trigger: useNetworkRestrictionsQuery runs before the project route param resolves (e.g. ref is still undefined on first render), or a component is mounted outside a project route so useParams returns undefined for ref.

Common situations: Settings page rendered during project switch; deep-linked settings tab loading before the project store hydrates; tests that mount the component without a projectRef in the wrapper.

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/47386ac1ef2fac13. Report an issue: GitHub.