How to fix EdgeFunctionRelayError: Relay request failed in Supabase

SupabaseINTERMEDIATEHIGHUpdated Dec 22, 2025· 186 views

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.

Quick fix

Fixes EdgeFunctionRelayError: Relay request failed

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)
}
  1. Check error instance and log details
  2. Test function locally with Supabase CLI
  3. Verify authentication and JWT tokens
  4. Check CORS configuration in function
supabase — error
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)
}
EdgeFunctionRelayError: Relay request failed

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.

Typical symptoms

  • Edge Function invocations fail intermittently with relay error messages
  • Network tab in browser dev tools shows failed requests with x-relay-error header
  • Function works locally with Supabase CLI but fails in production
  • Error occurs before function code executes, with no function logs generated
  • Authentication or JWT validation fails at the gateway level

Common causes

  1. Network connectivity issues between client and Supabase infrastructure
  2. Invalid or expired JWT authentication tokens in request headers
  3. CORS configuration issues preventing proper request relay
  4. Function execution exceeding the 60-second timeout limit at relay layer
  5. Request payload or headers exceeding gateway size limits
  6. Temporary infrastructure issues with Supabase edge gateway nodes
  7. Incorrect function URL or project reference in invocation code

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')
}

Advanced notes

Relay Error Types

The Supabase client library provides three distinct error types for Edge Functions:
- FunctionsRelayError: Network/routing issue between client and Supabase (this error)
- FunctionsHttpError: Function executed but returned an error response
- FunctionsFetchError: Function is not reachable or doesn't exist

Understanding the Relay Layer

The relay layer is Supabase's edge gateway infrastructure that:
- Routes requests to the appropriate Edge Function deployment
- Validates authentication headers and JWT tokens
- Applies rate limiting and traffic management rules
- Handles geographic routing to nearest edge nodes
- Enforces function execution timeouts (60 seconds)

Size Limits

Edge Functions have the following limits enforced at the relay layer:
- 10MB maximum source code size during deployment
- Request payload size limits (typically 6MB for POST/PUT bodies)
- Response size limits for streaming responses

Monitoring and Diagnostics

For production applications, implement comprehensive error monitoring:

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

if (error) {
  // Log to error tracking service (Sentry, LogRocket, etc.)
  errorTracker.captureException(error, {
    extra: {
      errorType: error.constructor.name,
      functionName: 'my-function',
      timestamp: new Date().toISOString()
    }
  })
}

If relay errors persist after troubleshooting, open a support ticket via the Supabase Dashboard with:
- Function name and project reference
- Error frequency and timing patterns
- Browser network tab screenshots showing x-relay-error header
- Output from local testing with --debug flag

Frequently asked questions

What does "EdgeFunctionRelayError: Relay request failed" mean?
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.
How do I fix "EdgeFunctionRelayError: Relay request failed"?
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 causes "EdgeFunctionRelayError: Relay request failed"?
Network connectivity issues between client and Supabase infrastructure Invalid or expired JWT authentication tokens in request headers CORS configuration issues preventing proper request relay
Is the "EdgeFunctionRelayError: Relay request failed" error serious?
Yes. This is a high-severity error that usually blocks work until it is fixed, but the steps above resolve it.

Official resources & further reading