Prerender Issue — IOEXT-1811 (maxVersion error) by bdenham · Pull Request #711 · commerce-docs/microsite-commerce-storefront

bdenham · 2026-01-30T03:38:18Z

Purpose of this pull request

This pull request (PR) updates the aem-prerender installation to document the fix to the error that NASM recently encountered:

The error occurs when running aio app build in a CI/CD pipeline. The app.config.yaml file has a productDependencies array, and at least one entry is missing the required maxVersion property.

The error message indicates:

Location: /productDependencies/0 (first entry in the array)
Missing property: maxVersion
Schema requirement: maxVersion is now required for each productDependencies entry

Associated JIRA ticket

https://jira.corp.adobe.com/browse/IOEXT-1811

Staging preview

Affected pages

https://experienceleague.adobe.com/developer/commerce/storefront/setup/configuration/aem-prerender/

…ash link

…/microsite-commerce-storefront into nasm-config-assets

Reverts changes lost in merge commit d5b5790. Restores: - ## How it works as proper heading - Tasks/Task components for installation steps - Options/Option components for troubleshooting - Full original content (757 lines) Co-authored-by: Cursor <cursoragent@cursor.com>

add empty line after title

meker12

Use AI to clean up the PR before pushing. If you download (update) the comdox toolkit, Dima added an /exl-validation and a /refactor command. I'm not sure how /exl-validation will work on the storefront content, but give it a try.

The refactor command was originally created for code, but I found that it works for reviewing the content and suggesting updates that improve content quality. Give it a try.

Co-authored-by: Margaret Eker <meker@adobe.com>

sirugh · 2026-02-05T17:37:41Z

+</TableWrapper>
+
+<Aside type="note" title="Commerce configuration">
+The prerender app reads Commerce configuration (endpoints, headers, and store context) from your storefront's `config.json` file, not from environment variables. Verify that your storefront has a properly configured `config.json` file with the required Commerce endpoints and headers as described in the <Link href="/setup/configuration/commerce-configuration/" text="Storefront configuration" /> documentation. For Adobe Commerce Optimizer, configure the appropriate headers (`AC-View-ID`, `AC-Source-Locale`, `AC-Price-Book-ID`) in your storefront's `config.json` file.


Suggested change

The prerender app reads Commerce configuration (endpoints, headers, and store context) from your storefront's `config.json` file, not from environment variables. Verify that your storefront has a properly configured `config.json` file with the required Commerce endpoints and headers as described in the <Link href="/setup/configuration/commerce-configuration/" text="Storefront configuration" /> documentation. For Adobe Commerce Optimizer, configure the appropriate headers (`AC-View-ID`, `AC-Source-Locale`, `AC-Price-Book-ID`) in your storefront's `config.json` file.

The prerender app reads Commerce configuration (endpoints, headers, and store context) from your site's configuration, not from environment variables. Verify that your storefront has a properly configured site configuration with the required Commerce endpoints and headers as described in the <Link href="/setup/configuration/commerce-configuration/" text="Storefront configuration" /> documentation. For Adobe Commerce Optimizer, configure the appropriate headers (`AC-View-ID`, `AC-Source-Locale`) in your site configuration.

AC-Price-Book-ID should be automatic based on user auth state after next "release", assuming configuration set up correctly (adobe-commerce-optimizer: true).

Also let's stop using the config.json term. It should be "site configuration".

sirugh · 2026-02-05T17:38:07Z

            generateSidebar(),
            {
-              exclude: ['/sdk/**', '/videos/**', '/dropins-b2b/**', '/merchants/storefront-builder/**'],
+              exclude: ['/sdk/**', '/videos/**', '/dropins-b2b/**', '/merchants/storefront-builder/**', '/get-started/howitallworks/**'],


What's "howitallworks"?

@sirugh — It's an artifact to fix the build when merging conflicts arise with the preview branch that holds lots of other PRs.

Sorry for the churn and extra changes that got into this PR. Moving forward:

I'll direct tech reviewers to the relevant files to review.

Keep the PRs slim (no refactoring) so the review is as simple as possible.

Tech reviewers should approve first, so they can be about their way.

Thanks for the feedback.

sirugh · 2026-02-05T17:43:43Z

I appreciate that we want to continually improve our docs, but I think sandbagging a big refactor when the issue is smaller makes it difficult to review or get changes out quickly.

Like, the PR description says:

The error occurs when running aio app build in a CI/CD pipeline. The app.config.yaml file has a productDependencies array, and at least one entry is missing the required maxVersion property.

So I would assume that the change might be a few lines, simple to review. But now that change is buried in a mountain of refactor. Are we meant to review the refactor or just the specific change that is the reason the PR was created?

sirugh · 2026-02-05T17:44:08Z

+
+**Commerce credentials** (Adobe Commerce Optimizer): Configure your Commerce backend connection according to your deployment type. For details on configuring Optimizer headers and endpoints, see the <Link href="/setup/configuration/commerce-configuration/" text="Storefront configuration" /> documentation for details.
+
+**Note**: The prerender app reads Commerce configuration (endpoints and headers) from your storefront's `config.json` file, not from environment variables. Before deployment, verify that `config.json` is correctly configured.


Same note re config.json vs "site configuration".

sirugh · 2026-02-05T17:46:06Z

+**Note**: The prerender app reads Commerce configuration (endpoints and headers) from your storefront's `config.json` file, not from environment variables. Before deployment, verify that `config.json` is correctly configured.
+
+<Aside type="caution" title="Required: maxVersion in productDependencies">
+If your `app.config.yaml` includes a `productDependencies` array, **each entry must include `maxVersion`**. Otherwise, the `aio app build` command fails with a validation error.


Does the prerender repo come with a "default" or "reference" app.config.yaml? If so, should we just fix it there instead of making a docs change?

Or, is this a scenario that happens in specific situations, like maybe productDependencies is added if you have some specific version of aio?

There is a default template; all that's needed after testing is to uncomment the lines and deploy. I'm not familiar with maxVersion. We have never used it.

baranovskyalexandr · 2026-02-06T18:24:04Z

+</TableWrapper>
+
+<Aside type="note" title="Commerce configuration">
+The prerender app reads Commerce configuration (endpoints, headers, and store context) from your storefront's `config.json` file, not from environment variables. Verify that your storefront has a properly configured `config.json` file with the required Commerce endpoints and headers as described in the <Link href="/setup/configuration/commerce-configuration/" text="Storefront configuration" /> documentation. For Adobe Commerce Optimizer, configure the appropriate headers (`AC-View-ID`, `AC-Source-Locale`, `AC-Price-Book-ID`) in your storefront's `config.json` file.


baranovskyalexandr · 2026-02-06T18:29:12Z

+**Note**: The prerender app reads Commerce configuration (endpoints and headers) from your storefront's `config.json` file, not from environment variables. Before deployment, verify that `config.json` is correctly configured.
+
+<Aside type="caution" title="Required: maxVersion in productDependencies">
+If your `app.config.yaml` includes a `productDependencies` array, **each entry must include `maxVersion`**. Otherwise, the `aio app build` command fails with a validation error.


There is a default template; all that's needed after testing is to uncomment the lines and deploy. I'm not familiar with maxVersion. We have never used it.

baranovskyalexandr · 2026-02-06T19:17:57Z

+**Correct format:**
+```yaml
+productDependencies:
+  - code: <PRODUCT_CODE>
+    minVersion: <MIN_VERSION>
+    maxVersion: <MAX_VERSION>  # Required
+```
+
+**Incorrect format (will cause build failure):**
+```yaml
+productDependencies:
+  - code: <PRODUCT_CODE>
+    minVersion: <MIN_VERSION>
+    # Missing maxVersion - build will fail
+```


I think it's not needed for this project

baranovskyalexandr · 2026-02-06T19:18:58Z

+### Enable automated synchronization
+
+After deployment, perform the following steps:
+- Use the <Link href="https://prerender.aem-storefront.com" text="Management UI" /> to start the change detector


The context will only appear here if we complete all the installation steps in the local environment.

baranovskyalexandr · 2026-02-06T19:19:27Z

-  - Update your `app.config.yaml` file and redeploy with `npm run deploy`
+<Option>
+
+### Build error: Missing maxVersion in productDependencies


Look at my comment above

baranovskyalexandr · 2026-02-06T19:19:56Z

+productDependencies:
+  - code: <PRODUCT_CODE>
+    minVersion: <MIN_VERSION>
+    maxVersion: <MAX_VERSION>  # Required field
+```


probably we should remove it

bdenham · 2026-02-07T16:32:00Z

Closed because they closed the ticket and @baranovskyalexandr told me it was not associated with prerender as I initially thought from early slack messages regarding the problem.

bdenham self-assigned this Jan 30, 2026

bdenham added the major-update Significant original updates to existing content label Jan 30, 2026

bdenham added 4 commits January 30, 2026 10:08

Fix build errors: exclude howitallworks from topics and fix invalid h…

1b1d78f

…ash link

Merge branch 'develop' into nasm-config-assets

5bf2135

Merge branch 'nasm-config-assets' of https://github.com/commerce-docs…

d7f111d

…/microsite-commerce-storefront into nasm-config-assets

Merge branch 'develop' into nasm-config-assets

ef8b69c

bdenham changed the title ~~Document the aem-prerender error for missing maxVersion property~~ Prerender error — no maxVersion property — IOEXT-1811 Feb 3, 2026

bdenham changed the title ~~Prerender error — no maxVersion property — IOEXT-1811~~ Prerender maxVersion property — IOEXT-1811 Feb 3, 2026

bdenham changed the title ~~Prerender maxVersion property — IOEXT-1811~~ Prerender — IOEXT-1811 (maxVersion error) Feb 3, 2026

bdenham changed the title ~~Prerender — IOEXT-1811 (maxVersion error)~~ Prerender Issue — IOEXT-1811 (maxVersion error) Feb 3, 2026

bdenham and others added 3 commits February 3, 2026 15:59

Merge branch 'develop' into nasm-config-assets

d5b5790

Merge branch 'develop' into nasm-config-assets

acb91ac

bdenham requested a review from meker12 February 5, 2026 01:36

meker12 added the feedback Update based on internal or external stakeholder feedback label Feb 5, 2026

Update aem-prerender.mdx

3603828

add empty line after title

bdenham requested a review from sirugh February 5, 2026 16:28

meker12 requested changes Feb 5, 2026

View reviewed changes

Apply suggestions from code review

b3d5f27

Co-authored-by: Margaret Eker <meker@adobe.com>

sirugh reviewed Feb 5, 2026

View reviewed changes

Merge branch 'develop' into nasm-config-assets

d3b0ae6

baranovskyalexandr reviewed Feb 6, 2026

View reviewed changes

bdenham added 2 commits February 6, 2026 14:03

Merge branch 'develop' into nasm-config-assets

38cd429

review updates

61a4eeb

baranovskyalexandr approved these changes Feb 6, 2026

View reviewed changes

bdenham closed this Feb 7, 2026

bdenham deleted the nasm-config-assets branch May 2, 2026 15:23


		Commerce credentials (Adobe Commerce Optimizer): Configure your Commerce backend connection according to your deployment type. For details on configuring Optimizer headers and endpoints, see the <Link href="/setup/configuration/commerce-configuration/" text="Storefront configuration" /> documentation for details.

		Note: The prerender app reads Commerce configuration (endpoints and headers) from your storefront's `config.json` file, not from environment variables. Before deployment, verify that `config.json` is correctly configured.

Conversation

bdenham commented Jan 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Purpose of this pull request

Associated JIRA ticket

Staging preview

Affected pages

Uh oh!

meker12 left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sirugh Feb 5, 2026 • edited by meker12 Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sirugh commented Feb 5, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bdenham commented Feb 7, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

bdenham commented Jan 30, 2026 •

edited

Loading

meker12 left a comment •

edited

Loading

sirugh Feb 5, 2026 •

edited by meker12

Loading