Troubleshooting

Use the following solutions to resolve common issues with App Management.

Configuration validation errors

The entire app.commerce.config is validated when the pre-app-build hook runs (for example during aio app build) and when you run npx aio-commerce-lib-app generate … manually. Schema validation is included. If validation fails, check:

1. Required properties. Fields must have name, label, and type.

2. Type-matched defaults. Default values must match the field type.

3. Valid metadata. App metadata must include id, displayName, description, and version.

App not appearing in App Management

1. Verify app is deployed:

   Copy
   aio app deploy --force-build --force-deploy
   Copied to your clipboard
   aio app deploy --force-build --force-deploy

2. Check runtime actions are generated in .generated folders.

3. Confirm valid configuration schema.

4. Verify correct organization in Developer Console.

Runtime actions not generated

1. Verify app.commerce.config exists with valid configuration.

2. Run a build so pre-app-build runs the generators:

   Copy
   aio app build
   Copied to your clipboard
   aio app build

3. If .generated folders are still missing or stale, run:

   Copy
   npx aio-commerce-lib-app generate all
   Copied to your clipboard
   npx aio-commerce-lib-app generate all

Encryption key errors

1. Validate your encryption key configuration.

   Copy
   npx aio-commerce-lib-config encryption validate
   Copied to your clipboard
   npx aio-commerce-lib-config encryption validate

2. Generate an encryption key (only creates one if it does not already exist).

   Copy
   npx aio-commerce-lib-config encryption setup
   Copied to your clipboard
   npx aio-commerce-lib-config encryption setup

Last updated 3/26/2026

Was this helpful?

Yes

No