How to monitor Supabase Edge Functions and catch silent failures
An Edge Function that starts failing returns an error to one caller and tells nobody else. Here is how to find the usual causes, and how to set up checks that alert you.
Updated
Short answer
Read the Invocations and Logs tabs for the function in the Supabase dashboard to see why it fails. To get alerted, add a small health function that checks the secrets the real functions need, point an HTTP monitor with a keyword check at it, and send a heartbeat ping from scheduled functions.
Monitor your Edge Functions freeWhy Edge Functions fail quietly
A broken function usually shows up as a failed request in your app, or as a scheduled job that did nothing. Supabase records every invocation, but it does not alert you when they start failing. Common causes:
| Cause | How to check | Fix |
|---|---|---|
| Secret missing or misnamed | Logs show an error where the code reads Deno.env.get('NAME') and gets nothing | Add it in the Edge Function Secrets page or with supabase secrets set NAME=value. No redeploy is needed. Names cannot start with SUPABASE_ |
| JWT verification rejects the caller | The function works from your app but fails from cron, a webhook or curl, and nothing appears in your own logs | verify_jwt is on by default and the platform checks the JWT before your code runs. For a public or service-to-service function, set verify_jwt = false and check the caller yourself |
| Request timeout | Invocations shows a 504 after a long wait | The request idle timeout is 150 seconds. Respond sooner and do slow work in the background |
| CPU or memory limit | The function dies on large payloads or heavy loops | CPU time is 2 seconds per request (waiting on I/O does not count) and memory is 256 MB. Process data in smaller pieces |
| Code error after deploy | Logs show an uncaught exception or a boot error | Fix the import or syntax error and deploy again. Run supabase functions serve locally first |
Cold starts are rarely the cause. Supabase describes initial executions as taking milliseconds. If a first request feels slow, the response time graph in your monitor will show it.
Read the logs in the dashboard
- Open Functions in the Supabase dashboard and select the function.
- Open Invocations for request and response details: headers, body, status code and duration. You can filter by status code.
- Open Logs for platform events, uncaught exceptions and your own
console.log,console.warnandconsole.erroroutput. You can filter by level or message text.
A function can log up to 100 events in a 10-second window, and one message can be up to 10,000 characters. Log the failing step and an ID, not a whole payload.
Add a health function
Monitoring a real function with a probe can have side effects, and it needs credentials. A separate, tiny health function avoids both. It should verify what your other functions depend on and return a distinct status code and body when something is wrong.
const REQUIRED_SECRETS = ['STRIPE_SECRET_KEY', 'RESEND_API_KEY'];
Deno.serve(() => {
const missing = REQUIRED_SECRETS.filter((name) => !Deno.env.get(name));
if (missing.length > 0) {
// Names only, never values.
return Response.json({ status: 'degraded', missing }, { status: 503 });
}
return Response.json({ status: 'ok' });
});[functions.health]
verify_jwt = falseDeploy it with supabase functions deploy health. It is then served at https://<project-ref>.supabase.co/functions/v1/health. Leaving JWT verification off is what lets a monitor call it without credentials, so return nothing sensitive from it.
The health function uses the same secrets store as your other functions, so a secret that is missing here is missing for them too. To check the database as well, query a small table from the health function and return 503 on error.
Heartbeat for scheduled functions
Supabase can run a function on a schedule with pg_cron and pg_net. The cron job posts to the function URL and moves on. If the function fails afterwards, the job still looks like it ran. Put a heartbeat ping at the end of the function, after the work succeeds.
Deno.serve(async () => {
try {
await runSync();
// Only reached when runSync() did not throw.
const heartbeatUrl = Deno.env.get('HEARTBEAT_URL');
if (heartbeatUrl) {
await fetch(heartbeatUrl, { signal: AbortSignal.timeout(10_000) });
}
return Response.json({ success: true });
} catch (error) {
console.error('nightly-sync failed', error);
return Response.json({ success: false }, { status: 500 });
}
});
async function runSync(): Promise<void> {
// Your job.
}Set HEARTBEAT_URL as a function secret. The URL looks like https://heartbeat.uptimeio.com/heartbeat/YOUR_HEARTBEAT_TOKEN; treat it like a password.
Two things on the cron side. A function called by pg_cron has no user JWT, so it needs verify_jwt = false and a check of the secret key in the apikey header, as described in the Supabase scheduling guide. Also keep the key in Vault instead of writing it into the job. pg_net is asynchronous and cancels a request after timeout_milliseconds, 2000 by default, so pass a larger value for slow functions. You can inspect past runs in the dashboard under the cron job's History button, or in cron.job_run_details.
Set it up in UptimeIO
- Create a Keyword monitor with your
healthfunction URL. Under HTTP Configuration the default is that only a200passes, which is right here. - Add the keyword
"status":"ok"as Contains, anddegradedas Excludes. - Pick a check interval. The shortest is 5 minutes on Free, 1 minute on Pro and 30 seconds on Scale.
- For each scheduled function, create a Heartbeat monitor and set the interval and grace period to cover your slowest run. Copy its URL into the
HEARTBEAT_URLsecret. - Choose where alerts go: email, Slack, Telegram, Pushover or a webhook.
- Keyword check: runs the HTTP request first, then searches the response body. Matching is plain text, not regular expressions.
- Heartbeat: an incident opens when a ping is late, and resolves after 3 on-time pings in a row.
- Status page: add these monitors to a status page so users can see when a function is degraded. The Free plan includes one.
Questions
- Where are Supabase Edge Function logs?
- In the dashboard under Functions: select the function, then use Invocations for requests and status codes, or Logs for platform events, uncaught exceptions and console output.
- Why does my Edge Function return 504?
- Supabase returns 504 Gateway Timeout when the function does not send a response within the 150 second request idle timeout. Respond earlier and move slow work out of the request.
- Do I need to redeploy after changing a secret?
- No. Supabase documents that deployed functions read a new secret immediately. A missing secret after a deploy usually means it was set on a different project or under a different name.
- How do I call an Edge Function from a monitor without a JWT?
- Create a dedicated health function and set verify_jwt = false for it in config.toml. Return only a status and the names of missing settings, never values.
- How do I know a pg_cron job actually succeeded?
- The cron history shows that the job ran, not that the function finished its work. Send a heartbeat ping from the end of the function and alert when it stops arriving.
Related
- API monitoring - Monitor endpoints for status, response time and response content.
- Cron job monitoring - How UptimeIO heartbeat monitoring works and which plans include it.
- Launch checklist for AI app builders - What to check before you send real users to an app built with Lovable, Bolt, Replit or v0.
- Keyword monitoring docs - Contains and Excludes keywords, matching rules and settings.