Maintenance Flag

The Apify Maintenance Flag (UNDER_MAINTENANCE) is a warning state applied to actors that fail Apify's automated quality checks for 3 consecutive days. When your actor is flagged, a prominent yellow warning banner appears on the actor's Store page telling potential users that the actor may not be working correctly. The actor also drops significantly in Store search rankings, reducing organic discovery and PPE revenue. Maintenance flags are the most common problem actors face on the Apify platform, and understanding how to prevent and resolve them is essential for any actor developer. Maintenance flags matter because they directly impact revenue, reputation, and user trust. A flagged actor signals to users that the tool is unreliable, causing them to choose a competitor instead. Even after the flag is resolved, the lost trust and reduced search ranking take days or weeks to recover. For developers with a portfolio of monetized actors, a single maintenance flag can reduce monthly revenue by 20-50% on that actor until the issue is fully resolved and the flag is cleared. Apify's automated quality system triggers maintenance flags based on several criteria. The most common trigger is dataset schema validation failures: if your actor pushes data that does not match the dataset schema (wrong types, missing required fields, unexpected null values, extra fields not in the schema), the push fails with a 400 error, the run fails, and after 3 consecutive days of failures on the default input, the flag is set. Other triggers include: actor builds that fail to compile (users cannot run the actor at all), runs consistently crashing on the default input (OOM errors, unhandled exceptions, missing environment variables), runs timing out on default input, and sustained failure rates above 50% over a 7-day window. To detect maintenance flags early, run the maintenance check script regularly: python scripts/check-maintenance.py. This script queries the Apify API for all your actors and reports which ones are flagged or at risk. You can also monitor via the API: GET /v2/acts/{actorId} returns a notice field that is non-null when the actor is under maintenance. Set up a webhook or scheduled check to alert you within hours of a flag being set, not days. To fix a maintenance flag: first, identify the root cause by checking the actor's run logs in the Console. Look at the most recent failed runs on default input — the error messages will indicate whether the issue is a schema mismatch, a build failure, a runtime crash, or a target site change. The most common fix is updating the dataset schema to match your actual output (or fixing your code to match the schema). After fixing the issue, push a new build with apify push, verify a successful run on default input, then clear the flag via the API: const client = new ApifyClient({ token }); await client.actor(actorId).update({ notice: null }); Or via HTTP: PUT /v2/acts/{actorId} with the body {'notice': null}. Common mistakes when handling maintenance flags include clearing the flag without fixing the underlying issue — the flag will be re-applied within 3 days when the automated checks fail again. Another mistake is not testing with the exact default input that Apify uses for quality checks. Your actor might work perfectly with custom input but fail on defaults because a required field has no default value, or the default URL is no longer valid. Always test by clicking Start in the Console without changing any input fields. Prevention is better than cure. To avoid maintenance flags: define a robust dataset schema and validate your output against it locally before pushing, set sensible defaults in your input schema so the actor works out of the box, monitor your actor's success rate weekly (target 95%+), test after every push, and subscribe to target site changes that might break your selectors. For web scraping actors, the target site changing its HTML structure is the most common cause of sudden maintenance flags — implement defensive selectors and fallback logic to handle minor HTML changes gracefully. Related concepts: Dataset Schema, Store Quality Score, Actor Build, Actor Run, Actor.