Why is my Apify actor under maintenance?

An Apify actor enters maintenance when the platform's automated quality system detects repeated failures over a multi-day window. According to Apify's maintenance policy, 2 failed auto-tests within 3 days triggers the maintenance flag, and 28 more days without a fix leads to deprecation. ApifyForge tracks these quality signals across your entire fleet so you can catch declining health before a flag appears.

The 4 most common causes

Apify's quality checks evaluate four areas. Here are the triggers ranked by how often they cause maintenance flags, based on patterns observed across actors managed through ApifyForge:

1. Dataset schema mismatch — Your actor's actual output does not match the declared dataset_schema.json. This is the most common cause and the hardest to spot manually because the actor runs successfully while silently producing non-conformant data. The ApifyForge Output Guard catches these mismatches locally in under 2 seconds before you push.
2. Low success rate — Your 7-day rolling success rate drops below approximately 80%. Even 3-4 failures in a week on a low-volume actor can cross this threshold. The ApifyForge dashboard displays per-actor success rates updated after every run.
3. Crash on default input — Apify periodically runs your actor with its default input configuration. If that run throws an unhandled exception, times out, or exits with a non-zero code, it counts as a failed auto-test.
4. Stale build — Actors that have not been rebuilt in 90+ days may receive a staleness flag, particularly if they depend on deprecated Node.js base images or outdated Crawlee versions.

How to diagnose the specific trigger

Step 1: Check the Apify Console for automated run results — navigate to your actor, filter runs by "System" origin, and look for recent failures. These auto-test runs happen every 1-3 days.

Step 2: Run the ApifyForge Output Guard against your actor to check for schema mismatches. Validation takes under 2 seconds and catches the #1 cause of maintenance flags.

Step 3: Check your 7-day success rate in the ApifyForge dashboard. A rate below 80% is a strong indicator the flag was triggered by cumulative failures rather than a single event.

Step 4: Review your build age. If your last build is older than 90 days, push a fresh build even if no code has changed — this resets the staleness clock and rebuilds against current base images.

How to resolve a maintenance flag

Resolving a maintenance flag requires fixing the root cause and then demonstrating consistent operation over several days:

Step 1: Identify the cause using the diagnostic steps above.

Step 2: Fix the issue — update your dataset schema, handle the failing edge case, increase timeout limits, or rebuild with current dependencies.

Step 3: Push a new build to Apify using apify push.

Step 4: Run your actor successfully with the default input at least 3-5 times over 2-3 days to rebuild your rolling success rate above 80%.

Step 5: Wait for Apify's periodic re-evaluation. The maintenance flag does not clear instantly — it typically takes 3-7 days of consistent clean runs before the system removes it.

Prevention checklist

Preventing maintenance flags is significantly more effective than resolving them after they appear. A single maintenance flag can reduce your Apify Store visibility for 1-2 weeks even after resolution, directly impacting PPE revenue. Use this checklist before every push:

• Run the ApifyForge Output Guard to verify output matches dataset_schema.json
• Run the ApifyForge Deploy Guard with default input to confirm the actor completes successfully
• Use Cloud Staging to test in the production environment — local runs may behave differently due to proxy routing, Docker configuration, or Node.js version differences
• Monitor fleet health in the ApifyForge dashboard to catch declining success rates before they cross the 80% threshold
• Rebuild actors at least once every 60 days to avoid staleness flags

For a deeper explanation of maintenance flags, see the ApifyForge glossary entry on maintenance flags. For testing strategies, see the actor testing guide. For debugging failed runs that contribute to maintenance flags, see the related help article on how to debug a failed Apify actor run.

Frequently asked questions

How long does it take for a maintenance flag to clear?

Apify re-evaluates actor health every 1-3 days. After fixing the underlying issue and running 3-5 successful auto-tests, the maintenance flag typically clears within 3-7 days. During this period, your actor remains usable but may appear lower in Apify Store search results.

Does a maintenance flag affect my PPE revenue?

Yes. Actors with a maintenance flag receive reduced visibility in the Apify Store, which means fewer users discover and run them. According to Apify's ranking algorithm, quality score — which includes maintenance status — directly influences Store placement. Lower placement leads to fewer runs and lower Pay Per Event revenue.

Can I prevent maintenance flags automatically?

ApifyForge provides automated monitoring that alerts you when an actor's success rate drops below configurable thresholds. The Deploy Guard can run regression tests across your fleet on a schedule, catching failures before Apify's auto-test system does. Combined with the Output Guard in your CI pipeline, these tools eliminate the most common maintenance flag triggers.

What is the difference between maintenance and deprecation?

Maintenance is a warning state — your actor still works and users can run it, but its Store visibility is reduced. Deprecation is permanent removal from the Apify Store. According to Apify's policy, an actor that remains in maintenance for 28 consecutive days without a fix is deprecated. Once deprecated, the actor must be re-submitted through the Store review process to be relisted.

My actor works locally but fails Apify's auto-test — why?

Environment differences between local and cloud runs are common. The top causes are: different Node.js versions (Apify uses the version specified in your Dockerfile base image), different proxy routing (local runs use your IP while cloud runs use Apify's datacenter proxies), Docker memory limits (the default is 256 MB unless you specify more in actor.json), and network timeouts (cloud runs may have different DNS resolution or firewall rules). Use ApifyForge Cloud Staging to test in the exact production environment.

Last updated: March 27, 2026