How to fix EdgeFunctionRelayError: Relay request failed in Supabase

SupabaseINTERMEDIATEHIGH

This error occurs when there's a network or routing issue between your client and Supabase's edge gateway. The relay layer handles authentication, routing, and traffic management for Edge Functions.

What this error means

The EdgeFunctionRelayError indicates a failure in the relay layer that sits between your client application and Supabase Edge Functions. This relay acts as an edge gateway that routes traffic, validates JWT tokens, applies authentication rules, and manages traffic routing to your deployed functions. When you invoke a Supabase Edge Function, the request passes through this relay infrastructure before reaching your function code. If the relay cannot successfully process or forward the request, it throws an EdgeFunctionRelayError. This is distinct from function execution errors (FunctionsHttpError) or unreachable function errors (FunctionsFetchError). The error is detected by checking response headers for 'x-relay-error' set to 'true', indicating the relay layer encountered a problem before your function could execute.

How to fix "EdgeFunctionRelayError: Relay request failed"

1Check error instance and log details

Import and check for the specific error type to get more context:

javascript

import { createClient, FunctionsRelayError } from '@supabase/supabase-js'

const supabase = createClient(url, key)

const { data, error } = await supabase.functions.invoke('my-function')

if (error instanceof FunctionsRelayError) {
  console.log('Relay error:', error.message)
  console.log('Error details:', error)
}

Check your browser's network tab for the failed request and look for the 'x-relay-error' header.

2Test function locally with Supabase CLI

Run the function locally to determine if the issue is with your function code or the relay infrastructure:

bash

supabase functions serve my-function --debug

Then invoke it locally:

javascript

const { data, error } = await supabase.functions.invoke('my-function', {
  headers: { 'x-region': 'local' }
})

If it works locally but fails in production, the issue is likely with the relay layer or network connectivity.

3Verify authentication and JWT tokens

Ensure your client has a valid authentication session:

javascript

// Check current session
const { data: { session } } = await supabase.auth.getSession()

if (!session) {
  console.log('No active session - authentication required')
}

// Refresh session if needed
const { data: { session: newSession }, error } = await supabase.auth.refreshSession()

The relay validates JWT tokens before forwarding requests. Expired or invalid tokens will cause relay failures.

4Check CORS configuration in function

Ensure your Edge Function returns proper CORS headers:

typescript

// In your Edge Function (index.ts)
Deno.serve(async (req) => {
  // Handle CORS preflight
  if (req.method === 'OPTIONS') {
    return new Response('ok', {
      headers: {
        'Access-Control-Allow-Origin': '*',
        'Access-Control-Allow-Headers': 'authorization, x-client-info, apikey, content-type',
      }
    })
  }

  // Your function logic here
  const data = { message: 'Success' }

  return new Response(JSON.stringify(data), {
    headers: {
      'Content-Type': 'application/json',
      'Access-Control-Allow-Origin': '*',
    }
  })
})

5Review function logs in Supabase Dashboard

Navigate to your Supabase Dashboard to check for errors:

1. Go to Edge Functions → [Your Function] → Logs
2. Look for relay errors, boot errors, or timeout issues
3. Check the function's boot time and execution duration
4. Verify the function isn't hitting the 60-second execution limit

If no logs appear, the request never reached your function, confirming a relay-layer issue.

6Verify function deployment and URL

Ensure your function is properly deployed and you're using the correct invocation:

bash

# Deploy with debug output
supabase functions deploy my-function --debug

# Verify function exists
supabase functions list

Check that your invocation uses the correct function name:

javascript

// Correct function name must match deployed function
const { data, error } = await supabase.functions.invoke('my-function', {
  body: JSON.stringify({ param: 'value' })
})

7Check for intermittent infrastructure issues

If the error is intermittent (affecting ~1% of invocations), it may be a temporary infrastructure issue:

1. Check Supabase status page for reported incidents
2. Monitor error frequency in your application logs
3. Implement retry logic with exponential backoff:

javascript

async function invokeWithRetry(functionName, payload, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const { data, error } = await supabase.functions.invoke(functionName, payload)

    if (!error || !(error instanceof FunctionsRelayError)) {
      return { data, error }
    }

    if (i < maxRetries - 1) {
      await new Promise(resolve => setTimeout(resolve, Math.pow(2, i) * 1000))
    }
  }

  throw new Error('Max retries exceeded for relay error')
}

How to fix EdgeFunctionRelayError: Relay request failed in Supabase

What this error means

Typical symptoms

Common causes

How to fix "EdgeFunctionRelayError: Relay request failed"

Advanced notes

Related errors

Official resources & further reading