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 free

Why 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:

CauseHow to checkFix
Secret missing or misnamedLogs show an error where the code reads Deno.env.get('NAME') and gets nothingAdd 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 callerThe function works from your app but fails from cron, a webhook or curl, and nothing appears in your own logsverify_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 timeoutInvocations shows a 504 after a long waitThe request idle timeout is 150 seconds. Respond sooner and do slow work in the background
CPU or memory limitThe function dies on large payloads or heavy loopsCPU 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 deployLogs show an uncaught exception or a boot errorFix 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

  1. Open Functions in the Supabase dashboard and select the function.
  2. Open Invocations for request and response details: headers, body, status code and duration. You can filter by status code.
  3. Open Logs for platform events, uncaught exceptions and your own console.log, console.warn and console.error output. 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.

supabase/functions/health/index.tsTypeScript
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' });
});
supabase/config.tomlTOML
[functions.health]
verify_jwt = false

Deploy 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.

supabase/functions/nightly-sync/index.tsTypeScript
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

  1. Create a Keyword monitor with your health function URL. Under HTTP Configuration the default is that only a 200 passes, which is right here.
  2. Add the keyword "status":"ok" as Contains, and degraded as Excludes.
  3. Pick a check interval. The shortest is 5 minutes on Free, 1 minute on Pro and 30 seconds on Scale.
  4. 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_URL secret.
  5. 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

Start monitoring in a few minutes

Start monitoring free

Free plan · 50 monitors · No credit card required