Netlify Scheduled Functions Debugging Guide 2026
Debug Netlify scheduled functions like a pro. Real error patterns, production patterns, and exact troubleshooting steps for indie hackers.
TL;DR
Netlify scheduled functions (v2.0+) fail silently by default. Enable CloudWatch logs, add structured logging with console.error(), check timezone handling, and verify cron syntax before deployment. Most issues stem from missing environment variables, incorrect cron expressions, or function timeout (15-minute limit).
---
The Silent Killer: Why Scheduled Functions Don't Report Errors
Unlike HTTP-triggered Netlify Functions, scheduled functions run in the background. If your function crashes, you won't see it in browser console. You'll only know something's wrong when your scheduled task stops working.
Real Console Error Messages You'll See
Error 1: Missing Cron Expression ``` Error: Unable to parse cron expression at parseCron (/var/task/node_modules/cron-parser/index.js:45:12) at handler (/var/task/index.js:12:3) ```
Error 2: Timeout Exceeded ``` Task timed out after 900.13 seconds at Timeout._onTimeout (/var/task/runtime.js:1078:23) ```
Error 3: Environment Variable Not Found ``` ReferenceError: Cannot read property 'split' of undefined at Object.<anonymous> (/var/task/index.js:8:15) ```
---
Setting Up Proper Logging
Netlify Functions integrate with AWS CloudWatch for v2.0+. You need explicit setup to see logs.
1. Enable Function Logs in netlify.toml
```toml [functions] node_bundler = "esbuild" memory = 1024 timeout = 30
[build] functions = "functions" ```
2. Production-Ready Logging Pattern
```javascript // functions/scheduled-task.js import { schedule } from '@netlify/functions';
const handler = async (event) => {
const startTime = Date.now();
const requestId = event.timerId || 'unknown';
try {
console.log([${new Date().toISOString()}] START scheduled-task requestId=${requestId});
// Your business logic here
const result = await processData();
const duration = Date.now() - startTime;
console.log([${new Date().toISOString()}] SUCCESS duration=${duration}ms result=${JSON.stringify(result)});
return {
statusCode: 200,
body: JSON.stringify({ success: true, data: result })
};
} catch (error) {
console.error([${new Date().toISOString()}] ERROR requestId=${requestId}, {
message: error.message,
stack: error.stack,
name: error.name
});
return {
statusCode: 500,
body: JSON.stringify({ success: false, error: error.message })
};
}
};
export const config = { schedule: "0 0 * * *" // Midnight UTC daily };
export default schedule(handler); ```
3. Access Logs in Netlify Dashboard
1. Site Settings → Functions 2. Click your function name 3. "View logs" tab shows recent executions 4. Filter by time range or search error messages
Verify in official docs: Netlify's function logs are stored for 7 days (verify in [Functions documentation](https://docs.netlify.com/functions/overview/)).
---
Common Debugging Patterns
Timezone Issues (The Biggest Trap)
Cron expressions in Netlify Functions run in UTC only. If you need 9 AM EST:
```javascript // WRONG - this won't work as expected export const config = { schedule: "0 9 * * *" // Runs at 9 UTC, not 9 EST };
// CORRECT - convert to UTC (9 EST = 14 UTC) export const config = { schedule: "0 14 * * *" // 9 AM EST = 2 PM UTC }; ```
Use [crontab.guru](https://crontab.guru) to validate expressions (it assumes UTC).
Environment Variables Not Loading
Scheduled functions don't auto-load .env.production. Explicitly set in Netlify UI:
```javascript const apiKey = process.env.EXTERNAL_API_KEY;
if (!apiKey) { console.error('EXTERNAL_API_KEY not found in environment'); throw new Error('Missing required environment variable'); } ```
Set via: Site Settings → Build & Deploy → Environment → Edit variables.
Timeout Management (15-Minute Limit)
Netlify scheduled functions timeout at 900 seconds (15 minutes) on free plans. Check your function config:
```javascript // netlify.toml [functions] timeout = 30 # seconds, max 900 ```
If your function needs longer processing:
---
Local Testing Without Deployment
Using netlify-cli v17.0+
```bash npm install -g netlify-cli@latest netlify dev --functions=functions ```
This starts a local server but does not execute scheduled functions automatically. You must manually trigger:
```bash
In another terminal
curl http://localhost:8888/.netlify/functions/scheduled-task ```Test Cron Parsing Locally
```javascript // test-cron.js const cronParser = require('cron-parser');
const expressions = [ "0 0 * * *", // Valid: daily "*/5 * * * *", // Valid: every 5 min "0 0 0 * *", // Invalid: too many fields ];
expressions.forEach(expr => {
try {
const interval = cronParser.parseExpression(expr);
console.log(✓ "${expr}" - Next run: ${interval.next().toString()});
} catch (e) {
console.log(✗ "${expr}" - ${e.message});
}
});
```
---
Monitoring & Alerting
Set up notifications for failed executions:
```javascript // Alert on failure pattern const handler = async (event) => { try { await risky_operation(); } catch (error) { // Send to external monitoring await fetch('https://your-alert-service.com/incident', { method: 'POST', body: JSON.stringify({ title: 'Scheduled function failed', timestamp: new Date().toISOString(), error: error.message, functionName: 'scheduled-task' }) }); throw error; } }; ```
Integrate with [error tracking setup](/?guide=netlify-error-tracking).
---
Verification Checklist
console.log() statements added for debuggingnetlify dev---
What am I missing?
Have you debugged tricky scheduled function issues? Share in comments:
Your real-world experience helps the community. Drop your debugging story below.