Index of every page on this site: llms.txt
All skills
jeremylongshore avatar

/apify-common-errors

@820dfc8
Run it yourself

Diagnose and fix common Apify Actor and API errors. Use when an Apify run fails, an API call returns 401/403/404/413/429, a proxy connection drops, an Actor build breaks, or a scrape hits an anti-bot block, and you need the cause plus a copy-paste fix. Trigger with "apify error", "fix apify", "actor failed", "apify not working", "debug apify", "apify 429".

Use this Skill: https://skilld.dev/gh/jeremylongshore/tons-of-skills-marketplace/apify-common-errors

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

referenceserror-reference.md

≈1.6k tokens on demand. Your agent reads this file only when SKILL.md points to it.

Apify Error Reference — Full Catalog

The ten most common Apify Actor and API errors, each with the raw error signature, root cause, diagnosis steps, and a copy-paste fix. Jump to the error whose signature matches your run log or API response.

  1. Actor Run Status: FAILED
  2. Actor Run Status: TIMED-OUT
  3. HTTP 429 — Rate Limited
  4. HTTP 401 — Unauthorized
  5. Actor Build Failed
  6. Proxy Connection Failed
  7. Anti-Bot Block (403/Captcha)
  8. Out of Memory
  9. Dataset Push Too Large
  10. Actor Not Found

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. </content> </invoke>

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts2mo3 checks · Risk SAFE
  • Gen Agent Trust Hub2mo

    The skill is safe and provides a comprehensive diagnostic reference for debugging Apify Actor and API errors. It uses standard command-line tools and official API endpoints to assist with troubleshooting and configuration fixes.

  • Socket2mo

    No alerts

  • Snyk2mo

    Risk: LOW · No issues

Signed by skilld at 820dfc8. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 4 months ago
What it can do
Runs commands
version
1.5.0
author
Jeremy Longshore <jeremy@intentsolutions.io>
tags
[
  "saas",
  "scraping",
  "automation",
  "apify"
]
All 3 allowed tools
Bash(curl:*)Bash(apify:*)Bash(npm:*)
Other metadata
compatibility
Designed for Claude Code

README badge

README badge for jeremylongshore/tons-of-skills-marketplace/apify-common-errors