Diagnose and fix common Apify Actor and API errors.
Use when encountering run failures, API errors, proxy issues,
or Actor crashes on the Apify platform.
Trigger: "apify error", "fix apify", "actor failed",
"apify not working", "debug apify", "apify 429".
Diagnose and fix common Apify Actor and API errors.
Use when encountering run failures, API errors, proxy issues,
or Actor crashes on the Apify platform.
Trigger: "apify error", "fix apify", "actor failed",
"apify not working", "debug apify", "apify 429".
Quick diagnostic reference for the most common Apify errors. Covers Actor run failures, API errors, proxy problems, anti-bot blocks, and platform-specific issues.
Prerequisites
Apify token configured
Access to Apify Console for log review
Error Reference
1. Actor Run Status: FAILED
Status: FAILED
StatusMessage: Process exited with code 1
Cause: Unhandled exception in Actor code.
Diagnosis:
// Check run log via APIconst client = newApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.run('RUN_ID').get();
console.log(run.statusMessage);
// Get the run logconst log = await client.run('RUN_ID').log().get();
console.log(log); // Full stdout/stderr output
Fix: Read the log, find the stack trace, fix the bug. Common causes:
Selector returns no results (page structure changed)
Unhandled promise rejection
2. Actor Run Status: TIMED-OUT
Status: TIMED-OUT
StatusMessage: Actor timed out after 3600 seconds
Cause: Actor exceeded its configured timeout.
Fix:
run = client.().(input, {
: ,
});
// Increase timeout when calling via client
const
await
actor
'user/actor'
call
timeout
7200
// 2 hours in seconds
// Or set in Actor configuration on platform
// Console > Actor > Settings > Timeout
Prevention: Reduce workload scope or increase maxConcurrency.
3. HTTP 429 — Rate Limited
ApifyApiError: Rate limit exceeded (429)
Cause: More than 60 requests/second to a single API resource.
Fix: The apify-client package retries 429s automatically (up to 8 retries with exponential backoff). If you still hit limits:
// Add delays between API callsimport { sleep } from'crawlee';
for (const item of items) {
await client.dataset(dsId).pushItems([item]);
awaitsleep(100); // 100ms between calls
}
// Better: batch push items (one API call)await client.dataset(dsId).pushItems(items); // Up to 9MB per call
4. HTTP 401 — Unauthorized
ApifyApiError: Authentication required (401)
Cause: Invalid, expired, or missing API token.
Diagnosis:
# Test your token
curl -s -H "Authorization: Bearer $APIFY_TOKEN" \
https://api.apify.com/v2/users/me | jq '.data.username'
Fix: Regenerate token at Console > Settings > Integrations.
5. Actor Build Failed
Build failed: npm ERR! code ERESOLVE
Cause: Dependency conflicts in package.json or Dockerfile issues.
Diagnosis:
# Check build log on platform
apify builds ls# Test build locally
docker build -t my-actor -f .actor/Dockerfile .
Fix: Run npm install locally first. Ensure package-lock.json is committed. Check Node.js version matches the base image.
6. Proxy Connection Failed
Error: Proxy responded with 502 Bad Gateway
ProxyError: Could not connect to proxy
Cause: Proxy configuration issue or proxy credits exhausted.
Fix:
// Check proxy configurationconst proxyConfig = awaitActor.createProxyConfiguration({
groups: ['BUYPROXIES94952'], // Verify group name in Console
});
// Test proxy connectivityconst proxyUrl = await proxyConfig.newUrl();
console.log('Proxy URL:', proxyUrl);
// Switch to residential if datacenter is blockedconst resProxy = awaitActor.createProxyConfiguration({
groups: ['RESIDENTIAL'],
countryCode: 'US',
});
7. Anti-Bot Block (403/Captcha)
Error: Request blocked — received status 403
Error: Captcha detected on page
FATAL ERROR: CALL_AND_RETRY_LAST Allocation failed — JavaScript heap out of memory
Cause: Actor memory allocation too low for the workload.
Fix:
// Increase memory when running via APIconst run = await client.actor('user/actor').call(input, {
memory: 4096, // MB — powers of 2: 128, 256, 512, 1024, 2048, 4096, ...
});
// Or reduce memory usage in Actor codeconst crawler = newCheerioCrawler({
maxConcurrency: 5, // Fewer concurrent pagesmaxRequestsPerCrawl: 1000, // Cap total requestsrequestHandlerTimeoutSecs: 30, // Fail fast on slow pages
});
9. Dataset Push Too Large
ApifyApiError: Payload too large (413) — max 9MB per request
Fix:
// Chunk large pushesfunction chunkArray<T>(arr: T[], size: number): T[][] {
constchunks: T[][] = [];
for (let i = 0; i < arr.length; i += size) {
chunks.push(arr.slice(i, i + size));
}
return chunks;
}
for (const chunk ofchunkArray(items, 500)) {
await client.dataset(dsId).pushItems(chunk);
}
10. Actor Not Found
ApifyApiError: Actor 'user/actor-name' not found (404)
Cause: Wrong Actor ID, or Actor is private and you lack access.
Fix: Actor IDs follow the format username/actor-name or the Actor's unique ID (alphanumeric). Check the correct ID at https://apify.com/username/actor-name.
Quick Diagnostic Commands
# Check Apify platform status
curl -s https://api.apify.com/v2/health | jq '.'# Verify your auth
curl -s -H "Authorization: Bearer $APIFY_TOKEN" \
https://api.apify.com/v2/users/me | jq '.data.username'# Check installed package versions
npm list apify-client apify crawlee 2>/dev/null
# Get last run status
curl -s -H "Authorization: Bearer $APIFY_TOKEN" \
"https://api.apify.com/v2/acts/USER~ACTOR/runs?limit=1&desc=true" | \
jq '.data.items[0] | {status, statusMessage, startedAt, finishedAt}'
