Apify Common Errors Skill

Apify Common Errors

Overview

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 API
const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.run('RUN_ID').get();
console.log(run.statusMessage);

// Get the run log
const 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:

Missing input validation (Actor.getInput() returns null)
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:

// Increase timeout when calling via client
const run = await client.actor('user/actor').call(input, {
  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 calls
import { sleep } from 'crawlee';

for (const item of items) {
  await client.dataset(dsId).pushItems([item]);
  await sleep(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 configuration
const proxyConfig = await Actor.createProxyConfiguration({
  groups: ['BUYPROXIES94952'],  // Verify group name in Console
});

// Test proxy connectivity
const proxyUrl = await proxyConfig.newUrl();
console.log('Proxy URL:', proxyUrl);

// Switch to residential if datacenter is blocked
const resProxy = await Actor.createProxyConfiguration({
  groups: ['RESIDENTIAL'],
  countryCode: 'US',
});

7. Anti-Bot Block (403/Captcha)

Error: Request blocked — received status 403
Error: Captcha detected on page

Cause: Target website detected scraping activity.

Fix:

const crawler = new PlaywrightCrawler({
  proxyConfiguration: await Actor.createProxyConfiguration({
    groups: ['RESIDENTIAL'],
  }),
  // Mimic real browser behavior
  launchContext: {
    launchOptions: {
      args: ['--disable-blink-features=AutomationControlled'],
    },
  },
  preNavigationHooks: [
    async ({ page }) => {
      // Randomize viewport
      await page.setViewportSize({
        width: 1280 + Math.floor(Math.random() * 200),
        height: 720 + Math.floor(Math.random() * 200),
      });
    },
  ],
  maxConcurrency: 3,  // Lower concurrency = less suspicious
  navigationTimeoutSecs: 60,
});

8. Out of Memory

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 API
const 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 code
const crawler = new CheerioCrawler({
  maxConcurrency: 5,              // Fewer concurrent pages
  maxRequestsPerCrawl: 1000,      // Cap total requests
  requestHandlerTimeoutSecs: 30,  // Fail fast on slow pages
});

9. Dataset Push Too Large

ApifyApiError: Payload too large (413) — max 9MB per request

Fix:

// Chunk large pushes
function chunkArray<T>(arr: T[], size: number): T[][] {
  const chunks: T[][] = [];
  for (let i = 0; i < arr.length; i += size) {
    chunks.push(arr.slice(i, i + size));
  }
  return chunks;
}

for (const chunk of chunkArray(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}'

Error Handling

| HTTP Code | Meaning | Retryable | Action | |-----------|---------|-----------|--------| | 400 | Bad request | No | Fix input/params | | 401 | Unauthorized | No | Check token | | 403 | Forbidden | No | Check permissions | | 404 | Not found | No | Verify resource ID | | 408 | Timeout | Yes | Retry with backoff | | 413 | Payload too large | No | Reduce batch size | | 429 | Rate limited | Yes | Auto-retried by client | | 500+ | Server error | Yes | Auto-retried by client |

Resources

Next Steps

For comprehensive debugging, see apify-debug-bundle.

Agent Skills: Apify Common Errors

Install this agent skill to your local

Skill Files