DocumentationExperience Cloud KCS

Resolving Dispatcher environment variables that don’t resolve or apply in AEM Dispatcher

Last update: June 27, 2026

Dispatcher environment variables fail to resolve, become unavailable inside IfDefine blocks, or behave inconsistently across environments when they’re mis-scoped, mis-named, assigned to the wrong service, referenced in unsupported directives, or overridden by an invalid dispatcher configuration. On AEMaaCS only ENVIRONMENT_DEV, ENVIRONMENT_STAGE, and ENVIRONMENT_PROD are injected as Apache defines, while custom Cloud Manager variables work only for string substitution and can’t be used inside IfDefine; on AMS, variables must be defined in /etc/sysconfig/httpd. Validating the variable definition, confirming it’s used in a supported context, and verifying the correct vhost loads at runtime restores the expected values.

Description description

Environments:

  • Adobe Experience Manager as a Cloud Service (AEMaaCS)
  • AEM Managed Services (AMS)
  • AEM Dispatcher (Apache) on Publish tiers
  • Dispatcher SDK for local validation

Issue/Symptoms:

  • A custom header outputs the literal variable name instead of the resolved value, such as Access-Control-Allow-Origin: ${VAR_NAME}.
  • The Dispatcher validator reports AH00111: Config variable ${VAR_NAME} is not defined.
  • Apache reports Bad Authority for an empty variable used in a virtual host.
  • IfDefine blocks fail to apply because ENVIRONMENT_STAGE or ENVIRONMENT_DEV isn’t detected.
  • The pipeline fails during dispatcher validation or deploy without a clear error, and the local validator shows undefined variables.
  • Environment-specific rules never execute because RDE has no ENVIRONMENT_RDE define.

Root cause:

Dispatcher variable resolution varies by platform and directive type. On AEMaaCS, only ENVIRONMENT_DEV, ENVIRONMENT_STAGE, and ENVIRONMENT_PROD are Apache defines; Cloud Manager variables are available only as string substitutions and can’t be used in IfDefine. Using variables inside unsupported directives (IfDefine, <If>, or an empty ServerName), or not defining them for both the pipeline and runtime, produces undefined values. When vhost symlinks or farm virtual-host mappings are incorrect, the wrong vhost file loads and the variables appear non-functional. Empty strings in a vhost ServerName or ServerAlias cause Apache runtime failures. AMS requires variables defined in /etc/sysconfig/httpd, and mismatched values across environments cause incorrect behavior.

How to confirm

  1. Confirm the variable exists and is correctly defined. In Cloud Manager, go to Program > Environment > Environment Variables and confirm the variable name (case-sensitive) and value match exactly what the dispatcher configs reference. Confirm the variable is defined for the Publish service, since the dispatcher isn’t present on Author tiers.
  2. Confirm the variable type is supported in the context where it’s used. AEMaaCS doesn’t support Cloud Manager environment variables inside IfDefine — only ENVIRONMENT_DEV, ENVIRONMENT_STAGE, and ENVIRONMENT_PROD work there. If you see IfDefine wrapping a Cloud Manager variable, that usage is unsupported.
  3. Confirm no variable resolves to an empty string, especially in vhosts. An empty FQDN variable in a ServerName produces the Apache Bad Authority error.

Resolution resolution

  1. Correct the variable definition or service assignment. If the name or value is wrong, or it’s assigned to the wrong service, add or correct the environment variable in Cloud Manager and rerun the pipeline.
  2. Use variables only in supported contexts. Keep Cloud Manager variables to string substitution, headers, rewrite rules, and vhost config. For environment-specific logic, use an Apache expression such as <If "${ENV:ENVIRONMENT_TYPE} == 'dev'"> or the ENVIRONMENT_DEV define instead of wrapping a custom variable in IfDefine.
  3. Define referenced variables in custom.vars. Add a Define entry for every variable referenced in the vhost files, in the form Define VAR_NAME ${varname}. With the definitions in place, the validator stops reporting AH00111: Config variable is not defined.
  4. Ensure vhost and farm symlinks are valid. Run the dispatcher validator locally; errors appear when enabled_vhosts or enabled_farms contain regular files instead of symlinks. Recreate the symlinks with ln -s under src/conf.d/enabled_vhosts and enabled_farms until the validator shows zero errors.
  5. Ensure the correct vhost loads at runtime. Confirm the farm files point to the correct virtualhosts.any file — an incorrect /virtualhosts mapping causes the dispatcher to load the default vhost and ignore custom variables. Correct the farm /virtualhosts block to include ../virtualhosts/virtualhosts.any, then visit a page and confirm the custom header shows the resolved value.
  6. For AMS only, set variables in /etc/sysconfig/httpd. SSH into the dispatcher server and run cat /etc/sysconfig/httpd to confirm the variables reflect the correct environment, then restart Apache with sudo systemctl restart httpd. If values revert, contact AMS Support.
  7. Test locally using the Dispatcher SDK. Run the dispatcher locally with the AEM SDK Dispatcher Tools, then confirm header resolution with curl -I http://localhost:8080/....

Validation

  1. Run dispatcher-sdk/bin/validate src and confirm no undefined-variable errors (AH00111) appear.
  2. Check the actual HTTP response headers with curl -I or browser DevTools and confirm the variables resolve to their Cloud Manager values.
recommendation-more-help
experience-cloud-kcs-help-kbarticles