Troubleshooting

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

Configuration validation errors

app.commerce.config is validated against its schema every time the config is loaded. This happens during the postinstall and pre-app-build hooks, and whenever you run an npx aio-commerce-lib-app generate … command manually. 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 get-url
   
   # Only if you don't see listed the `app-management` actions
   aio app deploy --force-build --force-deploy
   Copied to your clipboard
   aio app get-url
   
   # Only if you don't see listed the `app-management` actions
   aio app deploy --force-build --force-deploy

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

3. Ensure your commerce app configuration is valid.

4. Verify correct organization in Developer Console.

Runtime actions

Code generation is a mandatory step for App Management to work. The pre-app-build hook only regenerates the commerce app manifest (a snapshot of your config), and the configuration schema, so runtime actions must be generated manually with the following command (idempotent):

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

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

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

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

Encryption key errors

Generate an encryption key

Ensure your encryption key is present in the .env by running the command below. It only creates a new key if one does not already exist.

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

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

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

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

Validate your encryption key configuration.

If it's already there, validate it has the expected format:

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

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

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

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

Last updated 4/24/2026

Was this helpful?

Yes

No