The "EdgeFunctionError: Boot error" occurs when a Supabase Edge Function fails to initialize or start properly. This typically happens due to configuration issues, missing dependencies, syntax errors in the function code, or environment problems that prevent the Deno runtime from successfully booting the Edge Function.
The "EdgeFunctionError: Boot error" indicates that a Supabase Edge Function failed during its initialization phase before it could start processing requests. This is a critical error that occurs when the Deno runtime cannot successfully load and prepare your Edge Function for execution. Unlike runtime errors that happen during function execution, boot errors occur during the startup phase when: 1. The function's code is being parsed and compiled 2. Dependencies are being imported and resolved 3. Environment variables are being loaded 4. The function handler is being registered 5. The runtime environment is being initialized This error is particularly problematic because it prevents the function from running at all, meaning no requests can be processed until the boot issue is resolved. The error typically surfaces when deploying new functions, updating existing functions, or when there are changes to the function's dependencies or environment.
First, verify your Edge Function code has no syntax errors. Use TypeScript compiler locally:
# Check TypeScript compilation
npx tsc --noEmit --target es2020 --module esnext your-function.ts
# Or use Deno directly to check
deno check your-function.tsCommon syntax issues to check:
1. Missing imports: Ensure all imported modules are available
2. Type errors: Fix TypeScript type mismatches
3. Async/await issues: Ensure proper async function structure
4. Export errors: Make sure handler function is properly exported
Example of correct function structure:
// Correct: Proper async handler with export
import { createClient } from 'https://esm.sh/@supabase/supabase-js@2'
const corsHeaders = {
'Access-Control-Allow-Origin': '*',
'Access-Control-Allow-Headers': 'authorization, x-client-info, apikey, content-type',
}
export async function handler(req: Request) {
// Handle CORS preflight
if (req.method === 'OPTIONS') {
return new Response('ok', { headers: corsHeaders })
}
try {
// Your function logic here
const result = await processRequest(req);
return new Response(JSON.stringify(result), {
status: 200,
headers: { ...corsHeaders, 'Content-Type': 'application/json' }
});
} catch (error) {
console.error('Error:', error);
return new Response(JSON.stringify({ error: error.message }), {
status: 500,
headers: { ...corsHeaders, 'Content-Type': 'application/json' }
});
}
}Check that all imported modules are available and compatible with Deno:
// Common import issues and fixes:
// 1. Check import URLs - use esm.sh for npm packages
// BAD: import { something } from 'some-package'; // Won't work in Deno
// GOOD: import { something } from 'https://esm.sh/some-package';
// 2. Verify version compatibility
import { createClient } from 'https://esm.sh/@supabase/supabase-js@2'; // Specify version
// 3. Check for circular dependencies
// If file A imports B, and B imports A, you'll get boot errors
// 4. Test imports locally
deno cache --reload https://esm.sh/@supabase/supabase-js@2To diagnose import issues:
1. Check Deno cache: deno cache your-function.ts
2. Look for 404 errors: Missing modules will show as network errors
3. Verify CDN availability: esm.sh or other CDNs might be temporarily unavailable
4. Check version constraints: Some packages may not be compatible with Deno
If using private dependencies, ensure they're properly configured in your Supabase project.
Ensure all required environment variables are set and accessible:
# Check current environment variables in Supabase Dashboard
# Go to: Project Settings → API → Config
# Verify in your function code
console.log('Environment check:', {
hasSupabaseUrl: !!Deno.env.get('SUPABASE_URL'),
hasSupabaseKey: !!Deno.env.get('SUPABASE_ANON_KEY'),
// Add other required variables
});Common environment issues:
1. Missing variables: Required env vars not set in Supabase Dashboard
2. Incorrect names: Variable names don't match what code expects
3. Permission issues: Function doesn't have access to certain variables
4. Type mismatches: Code expects string but gets number/boolean
To fix:
1. Set variables in Supabase Dashboard:
- Go to Project → Edge Functions → Select function → Settings
- Add required environment variables
2. Use fallback values in code:
const supabaseUrl = Deno.env.get('SUPABASE_URL') || 'https://default.example.com';
const supabaseKey = Deno.env.get('SUPABASE_ANON_KEY') || 'default-key';
if (!supabaseUrl || !supabaseKey) {
throw new Error('Missing Supabase configuration');
}3. Test locally with .env file:
# Create .env file
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_ANON_KEY=your-anon-key
# Run function with env vars
supabase functions serve --env-file .envUse Supabase CLI to test functions locally before deployment:
# Install Supabase CLI if not already installed
# Follow: https://supabase.com/docs/guides/cli
# Start local development
supabase start
# Serve functions locally
supabase functions serve your-function
# Test the function
curl -X POST http://localhost:54321/functions/v1/your-function -H "Authorization: Bearer $ANON_KEY" -H "Content-Type: application/json" -d '{"test": "data"}'Local testing helps identify:
1. Boot errors before they reach production
2. Environment issues in local setup
3. Dependency problems during local execution
4. Network/connectivity issues
If local testing works but deployment fails:
1. Check Supabase project compatibility: Ensure local and remote versions match
2. Verify deployment command: supabase functions deploy your-function --project-ref your-project-ref
3. Check logs: Use supabase functions logs your-function to see deployment errors
4. Try incremental deployment: Deploy with --no-verify-jwt flag to isolate JWT issues
Ensure your code is compatible with the Deno runtime version used by Supabase:
// Check Deno version and features
console.log('Deno version:', Deno.version);
console.log('Deno features:', {
hasWebSocket: 'WebSocket' in globalThis,
hasCrypto: 'crypto' in globalThis,
hasFetch: 'fetch' in globalThis,
});
// Test Deno-specific APIs
try {
await Deno.readTextFile('./test.txt');
console.log('File API available');
} catch (error) {
console.log('File API error:', error.message);
}Common Deno compatibility issues:
1. Node.js APIs: Don't use Node.js-specific APIs (require, __dirname, etc.)
2. Global variables: Some browser globals may not be available
3. Permission model: Deno requires explicit permissions (network, env, read, etc.)
4. Module system: Uses ES modules, not CommonJS
Solutions:
1. Use Deno-compatible libraries: Check https://deno.land/x/ for Deno-native packages
2. Polyfill missing APIs: Use compatibility layers if needed
3. Check Supabase documentation: For supported Deno versions and features
4. Simplify code: Remove complex dependencies that may cause compatibility issues
Examine detailed logs to identify the specific boot error cause:
# Get deployment logs
supabase functions logs your-function-name --follow
# Filter for boot/initialization errors
supabase functions logs your-function-name | grep -i "boot|init|error"
# Check Supabase Dashboard logs
# Go to: Edge Functions → Select function → LogsCommon log patterns and fixes:
1. "Module not found": Add missing import or fix import URL
2. "Permission denied": Check file permissions and Deno permissions
3. "SyntaxError": Fix JavaScript/TypeScript syntax
4. "Memory limit exceeded": Reduce initialization memory usage
5. "Network error": Check internet connectivity during deployment
For persistent issues:
1. Create minimal reproduction: Strip function down to bare essentials
2. Deploy empty function: Test with just export async function handler() { return new Response("OK") }
3. Check Supabase status: Visit https://status.supabase.com for service issues
4. Contact support: Use Supabase Discord or GitHub discussions for help
## Understanding Edge Function Boot Process
The boot process for Supabase Edge Functions involves several stages:
1. Code Download: Function code is retrieved from storage
2. Dependency Resolution: All imports are fetched and cached
3. Compilation: TypeScript is transpiled to JavaScript (if needed)
4. Environment Setup: Environment variables are injected
5. Handler Registration: The exported handler function is registered
6. Runtime Initialization: Deno runtime prepares to receive requests
## Common Boot Error Scenarios
### 1. Cold Start Timeouts
If boot takes too long (typically >10 seconds), the function may fail with boot error. This can happen with:
- Large dependency trees
- Slow network connections to CDNs
- Complex initialization logic
### 2. Memory Constraints
Each Edge Function has memory limits (varies by plan). Boot process memory usage includes:
- Code size
- Imported module sizes
- Initial data structures
- Runtime overhead
### 3. Deno Version Incompatibility
Supabase may update Deno versions. Check:
# Check supported Deno version
supabase status### 4. Import Map Issues
If using import maps (deno.json), ensure:
- File is in correct location
- Imports resolve correctly
- No circular references
## Prevention Strategies
1. Minimal Dependencies: Only import what you need
2. Lazy Loading: Load heavy modules only when needed
3. Environment Validation: Validate all env vars on boot
4. Health Checks: Implement /health endpoint to verify boot success
5. Gradual Deployment: Use canary deployments for new functions
## Monitoring and Alerting
Set up monitoring for boot errors:
1. Log Alerts: Alert on "Boot error" in logs
2. Success Rate Monitoring: Track function initialization success rate
3. Cold Start Metrics: Monitor boot time duration
4. Dependency Health: Check external dependency availability
## Fallback Strategies
When boot errors occur in production:
1. Automatic Rollback: Revert to last working version
2. Circuit Breaker: Stop routing traffic to failing function
3. Graceful Degradation: Provide basic functionality without the Edge Function
4. Manual Intervention: Quick rollback via Supabase Dashboard
email_address_not_authorized: Email sending to this address is not authorized
Email address not authorized for sending in Supabase Auth
reauthentication_needed: Reauthentication required for security-sensitive actions
Reauthentication required for security-sensitive actions
no_authorization: No authorization header was provided
How to fix "no authorization header was provided" in Supabase
otp_expired: OTP has expired
How to fix 'otp_expired: OTP has expired' in Supabase
bad_oauth_state: OAuth state parameter is missing or invalid
How to fix 'bad_oauth_state: OAuth state parameter missing' in Supabase