Cause: The global npm bin directory isn't on your PATH, or the install ran against a different Node version than the one now active (common after switching Node via nvm/Homebrew after install).

Fix: Re-run npm install -g @adobe/aio-cli @adobe/aem-cli with Node 22 active, then open a new shell so PATH picks up the global bin directory.

Cause: A previous aio project on this machine left a different org selected — aio auth login doesn't reset the org selection by itself.

Fix: Run aio console org select, choose the correct organization for this workshop, then re-run aio where to confirm.

Cause: One of the two aio plugins:install commands failed silently (e.g. a network blip or npm registry timeout) or was skipped.

Fix: Re-run the missing plugin's install command individually, then re-check with aio plugins.

Cause: One of the seven chained npx skills add commands failed silently mid-chain (e.g. a network blip), so the && chain stopped before reaching the rest.

Fix: Re-run the failed skill's npx skills add command individually, then re-check ls .agents/skills/ for all seven directories.

Cause: The agent session was started (or its skill index cached) before the skills were installed, or it's running from a different working directory than the project root the skills were installed into.

Fix: Restart your AI coding agent session from the project folder root so it re-scans .agents/skills/.

Cause: You're signed in under the wrong IMS organization, or your org isn't entitled to the Commerce Migration Assessment application the CDA is hosted under.

Fix: Switch organizations in the Adobe ID org picker to match aio where's output; if the correct org still errors, flag it to your facilitator before Provisioning rather than troubleshooting further on your own.

Cause: A stale Adobe ID session, or a browser extension (ad blocker, strict cookie blocking) is interfering with the IMS sign-in redirect.

Fix: Retry in an incognito/private window with extensions disabled, or sign out of all Adobe ID sessions first and sign back in.

Cause: A previous Adobe ID session is still cached in the browser.

Fix: Sign out of all Adobe ID sessions (or use an incognito window), then sign back in and re-check the org picker.

Cause: The project wasn't auto-detected, or the demo URL has changed/moved.

Fix: Open the Sidekick menu and choose Add this project with the URL above, or try any other known https://main--repo--owner.aem.page/ site. Auto-detection failing here on your own storefront later (in Provisioning) has the same fix.

Cause: Edge disables extensions from outside the Microsoft Store by default.

Fix: Enable "Allow extensions from other stores" at edge://extensions, then retry the install.

Cause: The site has authentication for authors enabled and the Sidekick sign-in didn't complete.

Fix: Re-open the Sidekick menu and sign in again; retry in an incognito window if a stale session is interfering.

Cause: Provisioning in the selected region is degraded, or you don't actually hold the entitlement/quota to create a new instance in the chosen org.

Fix: Confirm your org and entitlement with your facilitator before retrying — don't click Add Instance repeatedly, since each attempt can consume credits per this instance's own metering rules.

Cause: This isn't a provisioning failure — the Adobe ID that provisioned the instance was never granted admin access on the "Adobe Commerce - Commerce Cloud Manager" product profile in Admin Console, so it maps into Commerce Admin as a restricted/developer-level user by default.

Fix: In Adobe Admin Console, have a System/Product Administrator add the affected user with admin permissions to the "Adobe Commerce - Commerce Cloud Manager" product profile, then log out and back in to Commerce Admin — the full menu appears immediately, no re-provisioning needed.

Cause: GitHub repository access wasn't authorized when prompted, or the GraphQL endpoint pasted from Commerce Cloud Manager is stale or incorrect.

Fix: Re-run Site Creator, explicitly grant GitHub access when prompted, and re-copy the GraphQL endpoint directly from Commerce Cloud Manager rather than reusing one from memory.

Cause: The active Node.js version in this shell doesn't match the Node 22+ installed in Tooling, or npm install didn't complete cleanly.

Fix: Confirm the active Node version matches Tooling Step 1's requirement, delete node_modules, re-run npm install, then retry npm start. > Gap in the outline, flagged explicitly: the worklab outline says > "Create ACCS instance (with sample data)." Nothing in the > commerce-practice-builder provisioning material supports that — it > states plainly that "the merchant's first blocker is an empty catalog, > not permissions" and that someone has to import data before a demo can > happen. Recommendation: treat sample-data import as an explicit, > separate task after instance creation (via Commerce Admin's Import tool > or the Product Visuals bulk-ingest flow), and don't assume a freshly > created ACCS instance ships with a catalog already loaded. Confirm with > your facilitator whether a pre-seeded catalog is provided for this > program, or plan ~15–20 extra minutes to import one before you need > products for cart testing in Extend Business Logic. A ready-to-import > 10-product sample (CSV + images) is linked under Resources below if you > need one on the spot.

Cause: The IMS OAuth Server-to-Server credentials in .env are missing, use the wrong Client ID/Secret, or weren't created against the Commerce Optimizer Ingestion API / Default - Cloud Manager profile.

Fix: Re-create the credentials in Adobe Developer Console following the exact API/profile named above, re-copy CLIENT_ID/CLIENT_SECRET into .env, and re-run the script.

Cause: The Storefront's GraphQL endpoint points at the wrong tenant ID or region, or ingestion wrote to a different environment (staging vs. production) than the Storefront queries.

Fix: Re-confirm the tenant ID and region from Commerce Cloud Manager, and make sure the TENANT_ID/REGION/ENVIRONMENT values used for ingestion match what's fed into Site Creator's GraphQL endpoint field.

Cause: These values come from the ACO instance's own detail view, not the ACCS one — easy to copy the wrong instance's identifiers when both exist in the same org.

Fix: Open the ACO instance specifically in Commerce Cloud Manager and copy its tenant ID/region directly, rather than reusing values noted for the ACCS instance.

Cause: Product Visuals is a distinct product from the AEM Sites/Edge Delivery entitlement that powers Storefront Builder — one doesn't imply the other.

Fix: Check entitlement explicitly before scoping this into a solution design (especially on PaaS, where it's a separate purchase) — don't infer it from "they already use AEM."

Cause: .agents/skills/ wasn't present (or wasn't in the folder the agent was actually running from) when the Agent Prompt ran. With no commerce-app-init/appbuilder-project-init skill to find, the agent fell back to a plain aio app init scaffold — a fallback that builds and deploys cleanly, so nothing signals the mistake until Confirm the Output or the Commerce Admin Associate step below.

Fix: Run ls .agents/skills/ from the same folder your agent is running in and confirm all seven skills from Tooling Step 2 are listed; if they're missing, install them there (Tooling Step 2) or restart the agent from the correct folder. Then re-run the Agent Prompt in a clean project folder — don't layer the Commerce scaffold on top of the generic one, undeploy/delete the generic attempt first.

Cause: App Management association requires a deployed app with generated App Management runtime actions (app-management/app-config at minimum) — a local build alone doesn't satisfy this check. On ACCS, a missing ACCS-REST-API subscription on the workspace can also block it.

Fix: Run aio app build && aio app deploy, confirm with aio runtime action list, and on ACCS subscribe ACCS-REST-API on the workspace (aio console workspace api add --projectName CommerceAppWorklab --workspaceName Stage --service-code ACCS-REST-API) before retrying Associate.

Cause: The deploy ran as aio app deploy --no-publish, which skips publishing the app's extension point (commerce/extensibility/1) to the Adobe Exchange registry. App Management's Associate flow checks that registry to confirm the app declares a valid Commerce extension point, so an unpublished app looks incompatible even though its runtime actions are live.

Fix: Re-run aio app deploy without --no-publish — check your deploy command, script, or agent instructions for a stray --no-publish flag first. Confirm the fix in the deploy output: it should list the extension point under New Extension Point(s) in Workspace. Then retry Associate.

Cause: Unlike most other APIs, ACCS-REST-API requires a license configuration (product profile) at subscription time.

Fix: Pass --license-config, e.g. aio console workspace api add --projectName CommerceAppWorklab --workspaceName Stage --service-code ACCS-REST-API --license-config "ACCS-REST-API=Default - Cloud Manager, Developers". If that profile name doesn't match your org, check the available profiles in the Developer Console's workspace API subscription UI.

Cause: Hyphens or other special characters were used in -n.

Fix: Use an alphanumeric-only name (e.g. CommerceAppWorklab) for -n, and put anything human-readable in -t (title) instead.

Cause: First-time wiring needs a Console configuration file downloaded first — there's no .aio to merge into yet.

Fix: aio console org select <org-id>, aio console project select CommerceAppWorklab, aio console workspace select Stage, then aio console workspace download workspace-config.json before aio app use workspace-config.json --no-input --overwrite.

Cause: App not deployed, or the app was never re-associated and installed after deploy.

Fix: Run aio app deploy, then unassociate/re-associate and complete the Install step in Commerce Admin, and confirm the hook appears for observer.sales_quote_item_save_before in the install summary.

Cause: Commerce applies a circuit breaker after repeated action failures (e.g. 400s). The hook still shows Active in Admin but is silently suspended internally.

Fix: Uninstall and reinstall the app from Commerce Admin. Toggling Active off/on is not sufficient to clear the suspended state.

Cause: That button only validates the webhook's declarative configuration inside Commerce — it never calls your Runtime action.

Fix: Test with a real add-to-cart from the storefront PDP and check aio runtime activation list or Commerce's own webhook debug logs.

Cause: The fields entry is using a dotted path as name without a separate source, or the source is missing bracket notation.

Fix: Use the exact name/source pair with bracket syntax: { name: "quote", source: "context_checkout_session.get_quote[items.qty,items.sku]" }.

Cause: Adding from the Product Listing Page drops the rejected-add exception message; this is storefront behavior, not a webhook defect.

Fix: Verify from the PDP, where the exception message renders correctly.

Cause: Commerce events not subscribed on the workspace, or the app was never re-associated and installed after deploy.

Fix: Add CloudIntegrationSDK and commerceeventing in Developer Console, then unassociate/re-associate and complete the Install step in App Management, then check Runtime logs for your action's activation.

Cause: Commerce eventing config requires a hyphenated package name (e.g. commerce-worklab); an underscored name (commerce_worklab) is rejected for the eventing package specifically, even though the Step 2 webhook package can use one.

Fix: Register event-driven actions under a separate hyphenated package. It's fine for webhook and event action packages to coexist in the same ext.config.yaml.

Cause: Fields extracted from the wrong path — the handler read params.data.entity_id instead of params.data.value.entity_id (CloudEvents wraps the Commerce payload one level deeper than a webhook payload).

Fix: Confirm the handler reads from params.data.value, and that entity_id/grand_total are declared in the event's fields array in app.commerce.config.ts.

Cause: App Builder Data Services API not subscribed on the workspace, auto-provision: true missing from app.config.yaml, or the app was never re-associated and installed after deploy so the custom installation step never ran.

Fix: Subscribe the API in Developer Console, confirm the database block in app.config.yaml, redeploy, then unassociate/re-associate and complete the Install step in App Management so setup-database.js runs. Verify with aio app db collection list.

Cause: include-ims-credentials: true is missing from the action's annotations, so no IMS token is injected.

Fix: Confirm annotations: include-ims-credentials: true on both the sync-order-to-erp action and the custom install action in ext.config.yaml. Rebuild and redeploy.

Cause: The handler is missing the state === "holded" guard, or is checking status on a payload field that isn't populated by the declared event fields.

Fix: Add state to the event's fields array in app.commerce.config.ts and check it in the handler before syncing.

Cause: The Admin UI SDK setting itself has to be switched on in Commerce Admin configuration — declaring the extension point in your app does not turn it on for the instance. This is a console/Admin toggle, not something an agent can flip for you.

Fix: In Commerce Admin, enable the Admin UI SDK for this app's extension, then reload the Admin menu.

Cause: The menu is very likely rendering correctly — just not where you're looking. adminUi.menu.parentMenu determines which existing Commerce Admin section (Sales, Catalog, Customers, Marketing, Content, Reports, Stores, or System) the entry nests under; there is no "Apps" option, and a custom menu never appears as its own top-level nav icon. It's easy to spend a long time re-checking registration, ACL, and caching when the actual gap is just not having expanded the right flyout.

Fix: Before troubleshooting anything else, find the exact parentMenu constant your agent used in app.commerce.config.ts (e.g. MENU_REPORTS), then expand that specific section in the Admin left nav. The entry shows up grouped under your app's display name inside that section's flyout menu, alongside that section's built-in items.

Cause: No ACL resource was declared for the menu entry, or the declared resource isn't actually being checked by the page/menu registration.

Fix: Confirm the extension declares an ACL resource ID and that it is referenced by the menu entry. Assign that resource explicitly to intended roles in System → Permissions → User Roles — an ungated Admin UI SDK entry defaults to visible for any role that can reach the parent menu.

Cause: The read action isn't using include-ims-credentials/the storage skill's DB auth pattern, so its DB connection silently fails or reads from the wrong scope.

Fix: Follow the same DB-auth wiring used for the sync-order-to-erp action in Step 4 above.

Cause: This is a known issue in certain versions of aio app build/aio app deploy's Parcel-based bundling, not a bug in your page code. A permanent fix is on the Admin UI SDK's backlog; in the meantime, the workaround below routes JSX through Babel instead.

Fix: Force Parcel to route JSX through Babel (in production mode) instead of its default SWC transform: 1. npm install -D @babel/core@^7 @babel/preset-react@^7 2. Add src/commerce-backend-ui-2/web-src/.babelrc: json { "presets": [["@babel/preset-react", { "runtime": "automatic", "development": false }]] } 3. rm -rf dist .parcel-cache && aio app build, then redeploy.

Cause: The image was pasted in as a link/URL instead of an actual embedded image in the document.

Fix: Insert the image directly into the document (drag-and-drop or the editor's image-insert action) rather than pasting a link — EDS only turns an embedded image into a picture element, not a text link.

Cause: The metadata table's rows don't use the expected key/value shape (a Title row and a Description row under a Metadata header), or the document wasn't saved before previewing.

Fix: Match the exact two-column Metadata table shape, save the document, and re-run da.live's Preview.

Cause: Preview and Publish are two separate actions — Preview only updates the staging (.aem.page) copy; Publish is required to push to production (.aem.live).

Fix: Click Publish in Sidekick, not just Preview, and give edge propagation a few seconds before reloading the production URL.

Cause: The table's header row text doesn't exactly match the block's expected name (Hero), so scripts/aem.js never recognized it as a block.

Fix: Confirm the table's header row reads exactly Hero (case and spelling matter) and republish.

Cause: The variation text must be inside parentheses directly after the block name in the table header — a typo or missing parentheses means scripts/aem.js never adds the extra class.

Fix: Confirm the header reads exactly Hero (dark) and that hero.css was saved and rebuilt (npm start) after adding the .hero.dark picture rule.

Cause: background was set on .hero or .hero.dark instead of .hero.dark picture. hero.css positions picture with z-index: -1 inside .hero, so an opaque background on .hero itself paints over the image and hides it.

Fix: Target picture specifically (.hero.dark picture { background-color: var(--color-neutral-900); }), not the block wrapper's own background.

Cause: The Hero image itself is a fully opaque photo with no transparent background — there's nothing for a background color to show through.

Fix: Either replace the image with one that has a real transparent background, or use filter: brightness(0.4) instead, which darkens the image directly regardless of transparency.

Cause: The subcopy paragraph has no color override in hero.css and inherits the default body text color, var(--color-neutral-800) — a dark gray with poor contrast against a dark background. Only the heading has its own override (var(--background-color), white).

Fix: Add .hero.dark p { color: var(--color-neutral-50); } alongside the background rule, so the dark variant overrides subcopy color the same way hero.css already overrides the heading's.

Cause: Same Edge Delivery caching/propagation behavior as Step 1 — the page needs to be republished from Sidekick and given time to propagate.

Fix: Republish (Preview → Publish) and re-check after a few seconds before assuming the block itself is broken.

Cause: The table's header row text doesn't exactly match the block's expected name (Product List Page), so it was never recognized as a block.

Fix: Confirm the table's header row reads exactly Product List Page (case and spelling matter) and republish.

Cause: The authored urlpath doesn't match a real category path in the catalog — a typo, or the category has no products marked visible in Catalog/Search.

Fix: Re-copy the category's URL key exactly from Commerce Admin's Catalog → Categories (or the storefront's nav bar) rather than guessing the path.

Cause: The DROPINS debug global is only exposed in a local/dev build, not a minified production build.

Fix: Run the overlay check against your local npm start server, not the published production URL.

Cause: The slot object was passed to the wrong container, or the block's decorate() never awaited provider.render(...) before appending to ctx.

Fix: Confirm the block imports SearchResults from @dropins/storefront-product-discovery/containers/SearchResults.js and that provider.render(SearchResults, { slots: {...} })(block) is awaited, matching the pattern used for other drop-in slot customizations in this storefront.

Cause: The ProductImage/ProductActions entries already in the block's slots object were replaced instead of kept alongside the new Header entry.

Fix: Confirm all three slot entries (ProductImage, ProductActions, Header) are present in the same slots object passed to provider.render(SearchResults, ...).

Cause: Edge Delivery caches config and content at the edge (up to ~2 hours max-age); the change hasn't propagated, or the page wasn't republished.

Fix: Republish the page from Sidekick (Preview → Publish) and wait for propagation rather than assuming the block logic is wrong. This is a known day-two "config seems to not apply" pattern for Edge Delivery storefronts, not specific to this block.

Cause: The block has no _<name>.json Universal Editor model — this is only required for visual editing, not for the block to function.

Fix: If merchandiser-friendly visual editing of the threshold field matters for your engagement, add a _product-list-page.json (or equivalent) model fragment and run npm run build:json to merge it into the root component-*.json files.

Cause: The Product Discovery drop-in isn't installed/registered in this project, or the import path doesn't match the pinned dropins version.

Fix: Check package.json for the installed @dropins/storefront-product-discovery version and confirm the export path against its own package.json exports map before assuming the prompt's path is exact.

Cause: PriceRange was given the wrong prop shape — the real prop names may differ from minimumAmount/maximumAmount depending on the dropins version.

Fix: Inspect an existing PDP/PLP block in this storefront that already renders a price with PriceRange and match its exact prop shape instead of guessing.

Cause: commerce-assets-enabled is set to false in config.json, so the storefront isn't resolving product images through the Commerce/AEM Assets image pipeline Image expects.

Fix: Check config.json and confirm commerce-assets-enabled is true before assuming the block's Image usage is wrong.

Cause: Same Edge Delivery caching behavior called out in Step 4 — the page needs to be republished from Sidekick and given time to propagate.

Fix: Republish (Preview → Publish) and re-check after propagation before assuming readBlockConfig() is broken.

Cause: The two blocks are importing separate Event Bus instances, or the click handler was wired before events was imported/available.

Fix: Confirm both blocks import events from the exact same @dropins/tools/event-bus.js path (a copy-paste from a different dropins version can resolve to a different module instance).

Cause: The product-compare-bar block's authored "Compare Page" row is missing, blank, or doesn't match /back-to-school (where Step 5's product-compare block actually lives).

Fix: Check the "Compare Page" row on the bar's authored table in da.live, and confirm the block logs a warning (rather than guessing a path) when that row is empty.

Cause: The product-compare block's query-param check either runs before the URL is updated, or wasn't added at all.

Fix: Re-check the Step 5 update described in the prompt above — the compare param must be read and preferred over the authored config before falling back to it.

Cause: A config error in mesh.json — often an unreachable source (the action isn't deployed yet, or the OpenAPI document's URL is wrong) or a deprecated transform.

Fix: Confirm the runtime action is deployed and reachable with a plain curl first, validate the OpenAPI document is valid JSON/YAML, and avoid replaceField (deprecated — use additionalResolvers instead).

Cause: API Mesh doesn't forward the client's Authorization header to the Commerce source by default. The login mutation succeeds (it needs no auth), but the storefront's follow-up authenticated customer query is sent through the mesh with no Authorization header, so Commerce rejects it with a graphql-authorization error ("The current customer isn't authorized") — which the storefront's login flow surfaces as a login failure.

Fix: Add "Authorization": "{context.headers.authorization}" to the Commerce source's operationHeaders in mesh.json, run aio api-mesh:update mesh.json, and retry — confirm with check #6 above before touching the storefront again.

Cause: The order type/field name guessed for targetTypeName/sourceArgs doesn't match the real Commerce GraphQL schema, or the Tracking source's OpenAPI document doesn't actually describe the response shape the resolver expects.

Fix: Introspect both schemas independently ({ __type(name: "CustomerOrder") {...} } against Commerce; a direct call against the Tracking source) before wiring additionalResolvers.

Cause: sourceArgs in additionalResolvers maps the wrong root field (e.g. {root.entity_id} when the order type's real identifier field is number), so the Tracking source never receives a matching order_id.

Fix: Match sourceArgs to the field actually available on root for that type — verify with a query that returns both the identifier field and the stitched trackingId together.

Cause: A known API Mesh limitation with the declarative additionalResolvers shorthand when the target field is a scalar (trackingId: String) but the source field it delegates to returns an object (generateTrackingId → { order_id, tracking_id }). Because the client's query has no sub-selection on a scalar field, Mesh has nothing to forward to the object-returning source field, and its automatic __typename handling for that delegation breaks.

Fix: Use a programmatic resolver instead (a mesh/additional-resolvers.js file referenced from additionalResolvers), and call the source field with an explicit selectionSet: '{ tracking_id }' so Mesh knows exactly which sub-field to fetch — see the code example in this step's Agent Prompt.

Cause: The mesh's Commerce source isn't forwarding a header core Commerce needs for this query — most commonly Authorization (see Step 1's login Troubleshooting entry for the exact failure signature), but also possibly Store/Magento-Store-Code/the ACO ac-view-id equivalent for multi-store setups — or CORS isn't configured for the storefront's origin on the mesh.

Fix: Confirm operationHeaders on the Commerce source forward Authorization ("{context.headers.authorization}") and any required store-scope headers, and that responseConfig.CORS.origin includes your storefront's exact origin (an explicit origin, not *, especially if credentials: true). As a fallback to isolate the issue, point commerce-core-endpoint directly at Commerce while keeping discovery through the mesh.

Cause: mesh.json has no responseConfig.CORS block (or one that doesn't list your dev origin), so the mesh doesn't send a matching Access-Control-Allow-Origin header on the preflight response — the browser blocks the request before it ever reaches the mesh.

Fix: Add a responseConfig.CORS.origin array to mesh.json that includes http://localhost:3000 (and your deployed storefront origin), run aio api-mesh:update mesh.json, and reload — don't use * if credentials: true is also set, since browsers reject that combination.

Cause: The order drop-in's own GraphQL query/fragment doesn't request the new field, so the container never receives it even though the schema supports it.

Fix: Update the drop-in's order query to include trackingId, and confirm the slot's onChange handler actually re-renders when new order data arrives.

Cause: The slot only renders inside the shipping-status container's per-shipment loop (e.g. a DeliveryTimeLine slot), which is skipped entirely when order.shipments is empty — the normal case for a Pending/unshipped order ("shipments": []). The slot callback never runs, even though the GraphQL fragment/model-transformer plumbing for trackingId is correct.

Fix: Render at the container level instead of the shipment-scoped slot — in blocks/commerce-shipping-status/commerce-shipping-status.js, prepend the "Tracking ID: …" text directly from the order/data listener rather than a per-shipment slot, so it renders for pending/unshipped orders too (adjust CSS margin/README to match).

Cause: Caching is enabled (responseConfig.cache: true) and the Tracking source doesn't return a public Cache-Control header, or a stale cached response is being served after the tracking ID was generated.

Fix: Check response headers for Cache-Status; if caching is on, purge with aio api-mesh:cache:purge -a after generating new tracking IDs, or don't cache this resolver's responses if tracking IDs must always be fresh.

Cause: Same mesh caching behavior as the Tracking source in Step 1 — a cached response is being served instead of a fresh call to the action.

Fix: Purge the mesh cache (aio api-mesh:cache:purge -a) after changing the business config, or disable caching on this resolver specifically since the whole point is that it must reflect the current config.

Cause: additionalTypeDefs conflicts with a Query field that already exists on the Commerce schema, or the OpenAPI document for ApprovalThreshold doesn't match the action's actual response shape.

Fix: Pick a field name that doesn't collide with the core schema (introspect first with { __type(name: "Query") { fields { name } } }), and validate the OpenAPI document against a direct curl of the action.

Cause: The fallback chain short-circuited too early — the mesh fetch likely threw before its result was checked, so the code fell straight through to the last fallback.

Fix: Wrap the mesh fetch in its own try/catch that falls through to the authored field on failure, keeping the hardcoded 500 as the last resort only.

Cause: The site isn't enabled for Experience Workspace, or the required setup is incomplete.

Fix: Re-run the guided setup tool, or run the demo from a prepared pilot site. Keep the core lab independent of this step.

Cause: The ew-setup tool itself is unreachable, or its access is restricted for this org.

Fix: Fall back to the manual setup documented on the Experience Workspace docs page (site/org config flags plus the Sidekick editUrlPattern config), or run the demo from a prepared pilot site.

Cause: The ew.enabled flag or the Sidekick editUrlPattern config wasn't set (guided setup incomplete or skipped), or ew.enabled is set but this particular author hasn't switched over yet.

Fix: In the document editor's header, toggle New Authoring on — a per-author setting that works even without the editUrlPattern change. If that toggle isn't there at all, re-run the guided setup tool to set the ew.enabled flag.

Cause: Chat may be disabled via ew.disableChat, or the current Early Access capability may differ.

Fix: Don't block the lab on the AI portion; continue with the Layout/Content view demonstration and document the limitation.

Cause: The MCP connector isn't configured for this workspace, or the session lost its connection.

Fix: Confirm the connector under the workspace's MCP settings before the lab starts; if it fails live, explain the capability and move on rather than troubleshooting MCP configuration in front of the group. > Facilitator note: this is intentionally a short tour, not a setup > exercise — the real campaign build starts in Step 2. Rehearse the > Commerce Storefront MCP query beforehand so it's not the first time you > see its answer; don't make an Early Access dependency part of the lab's > completion criteria, and don't let this step run long — it's an > appetizer, not the main build.

Cause: Preview reflects the last saved version of the document, and the edit hadn't finished saving yet.

Fix: Let the document finish saving (or save explicitly), then re-open Preview.

Cause: The link wasn't alone in its own paragraph (other text shared the line), or it wasn't wrapped in bold.

Fix: Put the link on its own line with nothing else in that paragraph, wrap it in **...**, and re-preview.

Cause: Edge propagation can take a few seconds, or Publish was clicked before the document finished saving.

Fix: Wait a few seconds and reload the live URL; if it still doesn't match, confirm the edit is saved in the document, then Publish again. > Facilitator note: keep this step tight — it's a quick recap/ > application of the Preview → Publish mechanic (already taught in Extend > Storefront), not a place to polish hero copy. Every step after this one > stays in Preview only, until Step 5 schedules the real launch — call > that pattern out now so it isn't a surprise later.

Cause: This storefront's default customer group for self-registration was reconfigured away from General, or the account was created directly in Admin under a different group.

Fix: In Commerce Admin's Customers > All Customers, edit the account's Account Information and set its Group to General directly, or check Stores > Customer Groups for a reassigned default.

Cause: The fragment path doesn't match where it was created, or it was never previewed after creation.

Fix: Confirm the fragment lives at exactly /fragments/promos/back-to-school-early-access (or -signin), and Preview it once on its own (using DA.live's Preview) before referencing it from the targeted block.

Cause: The Customer Groups value is wrong or missing, or the test shopper session isn't actually logged out.

Fix: Verify Customer Groups is set to the correct General group ID, and test the guest case in an incognito/private window.

Cause: The group ID doesn't match this storefront's actual General group — default IDs can be customized.

Fix: Confirm the real group ID in Commerce Admin's Customers > Customer Groups, and update the block's value to match.

Cause: The two targeted-blocks don't share the exact same Type value.

Fix: Make sure both blocks use identical Type: home-top. > Facilitator note: the cleanest demo is comparing a signed-in and a > signed-out preview side by side. Keep the lesson to contextual content, > not an exhaustive tour of every targeting option.

Cause: The agent's changes weren't committed/pushed yet, the deploy hasn't finished propagating, or the site-level config POST was never sent.

Fix: Confirm the agent committed and pushed its changes, give the deploy a minute to build, then confirm the POST to admin.hlx.page succeeded before reloading Sidekick.

Cause: The POST to the site's config replaced the whole sidekick.plugins array instead of merging into it.

Fix: GET the current config first, merge the aem-experimentation entry into the existing array, then POST the merged result back.

Cause: The wrong document was edited, or the edit wasn't saved before previewing.

Fix: Reopen the specific challenger (challenger-1 or challenger-2), confirm its change was made, and re-preview.

Cause: The link ended up alone in its own paragraph again (e.g. pasted on its own line, or still wrapped in bold) — that's exactly the pattern that triggers the site's button convention.

Fix: Confirm the link shares a paragraph with other subcopy text, and that it isn't wrapped in **...**, then re-preview.

Cause: The second variant row was never added in the Experimentation panel, or the panel was saved before setting variant-2.

Fix: Reopen the Experimentation panel on the control, add the missing variant row, set it to challenger-2's URL, and save again.

Cause: Publish was clicked in the Experimentation panel, or one of the three pages was published early.

Fix: Better to catch this now than on launch day — pause the experiment and unpublish the early page, then hold everything in Preview until Step 5's scheduled snapshot. > Facilitator note: this is the one step in the lab that touches the > storefront's code repo, not just content. The Agent Prompt covers the > repo-level wiring end to end; only the site-level Sidekick config POST > needs a human with admin access, so don't let participants skip it > waiting for the agent to do it.

Cause: This site hasn't been registered for scheduled publishing yet.

Fix: Follow the message's link to the Scheduler App (da.live/apps/scheduler) and register the site — self-service, no facilitator or API token needed — then retry.

Cause: One or more URLs are missing from the snapshot, or the snapshot wasn't approved.

Fix: Re-open the snapshot, confirm index, challenger-1, and challenger-2 are all listed in URLS, and confirm it shows as approved.

Cause: The snapshot was saved but never approved (Approve & Publish was skipped), or the scheduled date/time was set incorrectly.

Fix: Re-open the snapshot to confirm its approval status and scheduled date/time.

Cause: The snapshot bundled the pages as they were before the later edit — editing a document afterward doesn't automatically update a snapshot that already references it.

Fix: Re-open the snapshot and re-save it (or create a fresh one) so it picks up the latest content. > Facilitator note: this is the payoff for holding everything in > Preview since Step 3 — make the "everything launches together, on > schedule" moment explicit. This also replaces the scheduling approach > currently described in Operate Your Storefront's Step 1. Skipping > Request Review and self-approving is fine for this lab; in a real > launch, a second set of eyes on Approve & Publish is worth keeping.

Cause: It hasn't been added to this site's DA.live config yet — it's a one-time, per-site setup, not automatic.

Fix: Add the Library row under Install Commerce Picker above, then reopen the document.

Cause: That type needs more shopper history/data than this environment has collected yet — common on a fresh catalog.

Fix: Pick a type with a "ready" indicator instead; a product-anchored type like "Bought this, bought that" or "Viewed this, viewed that" is usually available even with a small dataset.

Cause: The anchor-based unit is missing its seed SKU, or the unit itself has no eligible results.

Fix: Confirm the seed SKU was set via Commerce Picker, and check the unit's configuration and catalog eligibility.

Cause: The search term doesn't match the product's indexed name, or the picker is scoped to a different catalog/view than the storefront uses.

Fix: Search by SKU instead of name, and confirm the picker's catalog view matches the storefront's configured one. > Facilitator note: this is the first time this lab uses the Commerce > Picker — pause to show what it actually returns (real, live catalog > data) versus hand-typing a SKU that might be stale or wrong.

Cause: package-lock.json is missing or out of sync with package.json — npm ci requires an exact lockfile match, unlike npm install.

Fix: Run npm install locally to regenerate the lockfile, commit it, and re-push.

Cause: marked is a devDependency; an npm ci --omit=dev or a production-only install step would skip it.

Fix: Use plain npm ci (no --omit=dev) since the build script itself is dev tooling, not a runtime dependency of the generated HTML.

Cause: aio app build alone doesn't need Developer Console credentials, but if the workflow also runs aio app use or any aio console command, it needs a Console context that a fresh CI runner doesn't have.

Fix: Keep build/test/config-drift credential-free (they only need the checked-in app.commerce.config.ts and ext.config.yaml); only the deploy job should need auth — see Step 3.

Cause: The check is comparing two things that are allowed to be briefly out of sync (config vs. prose), unlike sync-labs.mjs, which regenerates generated text from a single source of truth.

Fix: Treat config-drift failures as a prompt to update the relevant content/*.md page in the same PR, not as a hard merge blocker if the mismatch is a deliberate new key — consider a --check (warn) mode on PRs and a stricter mode only on main, matching sync-labs.mjs's own apply-vs-check split.

Cause: AIO_runtime_auth tokens obtained via aio app use have a limited lifetime; a value copied once into a long-lived GitHub secret will eventually expire.

Fix: Treat this as an operational gap to flag, not silently work around — neither source repo documents a service-account/long-lived-credential flow for headless aio auth in CI. Rotate the secret manually when deploys start failing, or investigate Adobe I/O's server-to-server / OAuth client-credentials options as a longer-lived alternative before relying on this for a production pipeline.

Cause: A debug/verbose flag on aio app deploy, or a shell step (e.g. env, cat .env) run for troubleshooting and left in the workflow.

Fix: Remove any command that dumps environment variables or file contents; rely on GitHub's automatic secret masking only as a backstop, not as the primary control.

Cause: Same as Tooling Step 3 — you're in the wrong IMS org, or the org isn't entitled to the Commerce Migration Assessment application CDA is hosted under.

Fix: Switch orgs in the Adobe ID picker to match aio where, and if the correct org still errors, flag it to your facilitator rather than troubleshooting further on your own.

Cause: You picked the experimental EDS track at project creation.

Fix: Start a new project and choose the App Builder track — the EDS track is experimental and out of scope for this lab.

Cause: Only the latest version can be approved — approval is meant to lock the newest agreed design as the contract.

Fix: Make sure the version you're viewing is the most recent one (create a fresh version if you've edited since), then approve that.

Cause: You already approved this version; an approved version is immutable so Develop can't be handed a moving target.

Fix: This is expected — tell CDA to save a new version, make your edits there, and re-approve when you're happy.

Cause: Expected — generation is high-quality scaffolding, not guaranteed production-ready code; validation exists precisely to catch what slipped through.

Fix: Don't hand-patch it in a panic — tell CDA what validation reported and have it fix the workspace, then re-run Validate workspace until it's clean. That fix-and-revalidate loop is the point of the step.

Cause: Validation proves the code builds and type-checks — it doesn't diff the generated code against your approved blueprint or plan tasks, so a piece can drift from the plan and still validate clean.

Fix: Tell CDA in chat exactly what's wrong or missing (name the plan task or blueprint detail it should match) and have it correct the workspace, then re-trace the plan into the code and re-run Validate workspace.

Cause: That API is the one CDA can't provision automatically — it needs a product profile selected when it's added. Either it wasn't added in the Developer Console, no product profile was picked, or you re-checked before re-importing an updated workspace.json.

Fix: In the Developer Console workspace, add Adobe Commerce as a Cloud Service and select the product profile(s); re-download workspace.json (via Download all on the Workspace overview page), re-import it into CDA, then Re-check status again — it should read All APIs subscribed.

Cause: The file you dropped isn't a workspace export — it's some other JSON (a project-level download, an unrelated config, etc.). CDA needs the workspace.json for the specific workspace, which carries its credentials and client secret.

Fix: In the Adobe Developer Console, open the specific workspace's Workspace overview (e.g. Stage) and click Download all to get workspace.json, then import that exact file — not a project export or any other JSON.

Cause: Deployment Ready tallies several checks — App Builder Connected, Required APIs Enabled, Credentials Validated, Secrets Stored, and the Project environment values; a missing project-env value keeps it below the bar.

Fix: Finish the App Builder step and fill the remaining Project Env values until the panel reads Deployment Ready.

Cause: The App Builder workspace isn't connected, so CDA has no target (project / workspace / runtime namespace) to run aio app deploy against.

Fix: Complete the App Builder step in Integrations (create or import a workspace) so the deploy has a target — and fill Project Env so the deployed app has the runtime values it needs.

Cause: A build- or deploy-time issue surfaced — a compile error, a bad config value, or a transient failure.

Fix: Ask CDA in chat to look at the failure and fix it, then redeploy — it can read the deploy log, patch the workspace, and re-run the deploy. Don't hand-patch blindly.

Cause: The app was deployed but never (re)associated and installed in Commerce Admin, so the event subscription isn't live on the workspace — and Commerce eventing is asynchronous.

Fix: Reassociate and reinstall the app in Commerce Admin → Apps → App Management, then re-check the activation logs for the capture_id, and fetch the webhook_capture read endpoint to confirm the payload arrived.

Cause: The app was deployed with Project Env incomplete, so a runtime value the code expects is missing. Deploy is gated only on App Builder, so this can ship a misconfigured app.

Fix: Fill the remaining values on Integrations → Project Env, then redeploy.

Cause: No repository is connected yet, or the connection wasn't completed (repo URL missing, or the GitHub App / token step wasn't finished).

Fix: In Integrations → GitHub, enter the repository URL and complete the GitHub App (an admin installs it once) or Personal Access Token connection; the icon turns green once it's linked.

Cause: The GitHub App is installed for "Only select repositories" and your target repo isn't in that list (or a PAT lacks repo write scope), so CDA can't push a branch.

Fix: It depends on how you connected. GitHub App — add the target repository under GitHub → Settings → Applications → [the installed CDA app] → Repository access (or choose All repositories) and Save. Personal Access Token — recreate the token with write access to the repo's contents and pull requests, then reconnect it in Integrations → GitHub. Either way, retry Create PR afterward.

Cause: The branch name you entered collides with an existing branch on the repo.

Fix: Use a fresh branch name and create the PR again.

Cause: require-adobe-auth: true alone isn't enough for a worker mass action — Commerce calls it with an IMS token, and the action registration itself needs final: true so the bound inputs stay locked, same as any other Admin UI SDK worker action.

Fix: Confirm the action's annotations match the commerce-app-admin-ui skill's worker-variant example exactly (require-adobe-auth: true, final: true), and that it's declared under its own package in src/commerce-backend-ui-2/ext.config.yaml, not the extensibility extension's ext.config.yaml where the event/webhook actions live.

Cause: Reused insertOne instead of an upsert-capable write (updateOne/findOneAndUpdate with upsert: true) against the erp-sync collection.

Fix: Switch the write to an upsert keyed on order_id, and remember aio-lib-db's findOne throws instead of returning null when nothing matches (see Extend Business Logic, Step 3) — the "does a record already exist" check needs the same try/catch treatment here.

Cause: require-adobe-auth: true rejects requests missing the x-gw-ims-org-id header — a valid bearer token alone isn't enough. This bit the ERP Sync Status menu page too during the live build.

Fix: Send both Authorization: Bearer <imsToken> and x-gw-ims-org-id: <imsOrgId> (both available from useIms()'s data).

Cause: The registered path in app.commerce.config.ts and the route's path in app.tsx don't match character-for-character (including the leading #/).

Fix: Copy the path string verbatim between the config entry and the app.tsx route — don't retype it in either place.

Cause: The response's row keys don't match the id declared in gridColumns.columns — grid columns render strictly by key match, falling back to a defaults bag otherwise.

Fix: Make sure the key you set in the response object is character-for- character the same as the column's id in config.

Cause: fields is a Commerce-event-only property; external events don't support field extraction at all — the handler always receives the full payload.

Fix: Remove fields from the external event entry entirely.

Cause: after webhooks are observational — Commerce doesn't do anything with an op: "exception" or fallback_error_message response there the way it does for before hooks. A handler written like a before hook (expecting to block) will just silently have no visible effect.

Fix: Have the handler's success path perform the actual side effect (here, calling Commerce's REST API to add the order comment) rather than returning a response Commerce would only act on for a before hook.

Cause: The config library can return the boolean's underlying value as the string "false" rather than the boolean false, depending on how the schema field resolves it — a truthy check on the raw value passes even when it "looks" false.

Fix: Coerce explicitly (e.g. compare against the string "false", or use the same numeric/string coercion pattern already used for order_approval_threshold) instead of relying on JS truthiness.

Cause: This workshop's app was built step by step through agent prompts without a pass dedicated to documentation — expected for a training app, but exactly what a real submission review would catch too.

Fix: Ask your agent to generate the missing documentation from the app's actual app.commerce.config.ts and ext.config.yaml content, then re-run the review.