supabase/supabase · error · Error

projectRef is required

Error message

projectRef is required

What it means

Thrown by getAPIKeys() when projectRef is falsy, before GET /v1/projects/{ref}/api-keys (the list endpoint). projectRef supplies the `{ref}` path segment. reveal is an optional query param controlling whether secret values are returned; it is not guarded. Returns APIKey[] (union of legacy/secret/publishable keys).

Source

Thrown at apps/studio/data/api-keys/api-keys-query.ts:55

  hash?: string
  id: string
  inserted_at: string
  name: string
  prefix?: string
  secret_jwt_template?: { role: string } | null
  type: 'publishable'
  updated_at?: string
}

interface APIKeysVariables {
  projectRef?: string
  reveal?: boolean
}

export type APIKey = LegacyKeys | SecretKeys | PublishableKeys

async function getAPIKeys({ projectRef, reveal }: APIKeysVariables, signal?: AbortSignal) {
  if (!projectRef) throw new Error('projectRef is required')

  const { data, error } = await get(`/v1/projects/{ref}/api-keys`, {
    params: { path: { ref: projectRef }, query: { reveal } },
    signal,
  })

  if (error) handleError(error)

  // [Jonny]: Overriding the types here since some stuff is not actually nullable or optional
  return data as unknown as APIKey[]
}

export type APIKeysData = Awaited<ReturnType<typeof getAPIKeys>>

export const useAPIKeysQuery = <TData = APIKeysData>(
  { projectRef, reveal = false }: APIKeysVariables,
  { enabled = true, ...options }: UseCustomQueryOptions<APIKeysData, ResponseError, TData> = {}
) => {

View on GitHub (pinned to beee91b9c2)

Solutions

1. Gate the query on `enabled={!!projectRef}`.
2. Resolve the selected project before rendering the API-keys list.
3. When calling getAPIKeys directly, supply a non-empty projectRef.
4. Tighten projectRef to required `string` in APIKeysVariables at the hook boundary.

Example fix

// before
useAPIKeysQuery({ projectRef, reveal }, { enabled: true })
// after
useAPIKeysQuery({ projectRef, reveal }, { enabled: !!projectRef })

const enabled = !!projectRef

function hasAPIKeysRef(v: APIKeysVariables): v is APIKeysVariables & { projectRef: string } {
  return !!v.projectRef
}

When it happens

Trigger: useAPIKeysQuery runs before the project ref is available, or with enabled forced true while projectRef is undefined; the API-keys list page mounts before the project context hydrates.

Common situations: The API-keys settings page loads from a deep link before the selected project resolves; the page is rendered outside a project scope; a project switch leaves the query briefly enabled with no ref; test fixtures omit projectRef.

Related errors

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

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