Most AEM migration guides talk about infrastructure and pipelines. Fewer talk about what actually breaks at the component level when you move AEM Sites code to Cloud Service. Here's a practical checklist based on real migration work.

1. Audit every OSGi Console dependency in your components

If any component logic reads config directly from /system/console/configMgr assumptions, or your devs used the OSGi console to hot-patch configs in prod, that workflow is gone. Cloud Service requires all OSGi configs to be defined as .cfg.json files in your repo and deployed through the pipeline. Grep your codebase for any code that assumes runtime-editable config it needs to move to proper config nodes per run mode (dev, stage, prod).

2. Replace JCR_SQL2 and XPath queries with indexed, cloud-safe queries

Cloud Service's Oak indexing is stricter about unindexed traversal queries anything that ran fine on-prem with a small index footprint can silently time out or get throttled in the cloud. Run the Oak Index Definition validation and check oak:index custom indexes are actually deployed with your content package, not manually created via CRXDE (which no longer exists in prod).

3. Rewrite any component that touches the filesystem directly

Components that write temp files, cache images to local disk, or read from /etc filesystem paths outside the JCR will fail Cloud Service Publish instances are ephemeral and don't guarantee persistent local storage across restarts/autoscaling events. Move any of this to the JCR itself, a proper cache implementation, or an external service.

4. Check your HTL templates for deprecated Sling API usage

Common flags from Cloud Manager's rule engine:

• SlingHttpServletRequest.getResourceResolver().adaptTo(Session.class) used directly in HTL-backed models - this pattern is heavily discouraged in the cloud SDK.
• Direct ResourceResolverFactory.getAdministrativeResourceResolver() calls banned in Cloud Service builds outright, causes a hard failure in Cloud Manager code quality gates.

5. Validate your client libraries against the new dispatcher caching rules

Cloud Service's dispatcher config is validated at build time with stricter rules than on-prem: no overly permissive /clientlibs cache rules, mandatory Cache-Control headers, and no wildcard allow patterns. If your clientlib structure was ad-hoc (mixed vendor/site libs, inconsistent categories), this is the moment to clean it up it'll get flagged either way.

6. Test your workflows against the new Workflow launcher restrictions

Custom workflow steps that call synchronous external APIs (PIM lookups, DAM enrichment services) during a page publish event can cause publish timeouts under Cloud Service's stricter execution limits. Move long-running work to async processing (Sling Jobs) instead of blocking the workflow thread.

Bottom line: most component-level migration bugs come from patterns that "worked fine" on-prem because the environment was forgiving local disk, admin resolvers, unindexed queries. Cloud Service removes that forgiveness. Auditing for these six patterns before migration saves weeks of firefighting after cutover.

Anyone hit migration bugs that weren't on this list? Curious what else caught people off guard at the component level specifically.