How do I debug a failed Apify actor run?

Start with the run log in the Apify Console — it contains the error message, stack trace, and timeline of what happened during the run. Navigate to your actor, click the failed run, and read the log from the bottom up to find the error that caused the failure. Here is a systematic debugging process. Step one: identify the error type from the run log. Look for these common patterns. An unhandled exception shows a JavaScript Error with a stack trace pointing to the exact file and line number — this is usually the easiest to fix because the location is explicit. A timeout error means the actor exceeded its time limit, which could indicate infinite loops, slow network requests, or the target website rate-limiting your requests. An out-of-memory error means the actor tried to use more RAM than its allocated memory (check the actor.json memory setting). A network error like ECONNREFUSED, ETIMEDOUT, or HTTP 403/429 means the target website is unreachable or blocking your requests. Step two: reproduce the failure locally. Copy the exact input from the failed run (available in the run details), run the actor locally with apify run, and observe whether the same error occurs. If it reproduces locally, you can debug with standard Node.js debugging tools — console.log, the Node.js debugger, or VS Code's built-in debugger. If it does not reproduce locally, the issue is likely environment-specific (different Node.js version, Docker configuration, proxy behavior, or network routing). Use Cloud Staging to test in the production environment. Step three: check for common causes specific to each error type. For timeouts — add progress logging to identify where the actor gets stuck, reduce the scope of work per run, implement request queuing with configurable concurrency. For out-of-memory — reduce batch sizes, stream data instead of loading everything into memory, increase the memory allocation in actor.json. For 403/429 blocking — add or upgrade proxies, reduce request rate, add random delays, switch from Cheerio to Playwright for JavaScript-heavy sites. For fleet-wide debugging, the ApifyForge dashboard shows failure trends across all your actors, helping you identify whether failures are isolated incidents or systemic issues (like a proxy provider outage or a target website redesign). For prevention strategies, see the related questions about the Test Runner, Schema Validator, and what happens when an actor fails.