ForgeRock Identity Platform
Does not apply to Identity Cloud

502 Bad Gateway error when an Amster (All versions) command fails

Last updated Jan 11, 2023

The purpose of this article is to provide assistance if an Amster command fails and you see an "Unhandled server error: [Status: 502 Bad Gateway]".

1 reader recommends this article


Amster connects successfully, but subsequent commands (for example, export-config) fail.

One of the following 502 Bad Gateway responses is shown when an Amster command fails:

  • ERROR org.forgerock.openam.sdk.http.ServerErrorException: [main] ERROR org.forgerock.openam.sdk.http.DefaultErrorHandler - Unhandled server error: [Status: 502 Bad Gateway] ERROR org.forgerock.openam.sdk.http.ServerErrorException: 502 Bad Gateway   at org.forgerock.openam.sdk.http.DefaultErrorHandler.onServerError (    at org.forgerock.openam.sdk.http.HttpSessionImpl.handleUnsuccessfulResponse (    at org.forgerock.openam.sdk.http.HttpSessionImpl.send (    at (    at org.forgerock.openam.sdk.crest.CrestResourceProviderAsync.actionCollection (    at org.forgerock.openam.sdk.crest.HttpCrestResourceProvider.actionCollection (    at org.forgerock.openam.sdk.operations.CrestOperations.action (    at org.forgerock.openam.sdk.operations.CrestOperations.action (    at org.forgerock.openam.amster.loadster.EntityTypeProvider.getCustomSubEntityTypes (EntityTypeProvider.groovy:168)    at org.forgerock.openam.amster.loadster.EntityTypeProvider.getCustomEntityTypes (EntityTypeProvider.groovy:157)    at org.forgerock.openam.amster.loadster.EntityTypeProvider.getEntityTypes (EntityTypeProvider.groovy:102)    at org.forgerock.openam.amster.loadster.EntityTypeProvider.getGlobalEntityTypes (EntityTypeProvider.groovy:84)    at org.forgerock.openam.amster.loadster.importer.Importer.<init> (Importer.groovy:72)
  • ERROR [main] ERROR - Unhandled server error: [Status: 502 Bad Gateway] ERROR Unable to provision, see the following errors: 1) Error in custom provider, 502 Bad Gateway    at Source)    at Source) while locating for parameter 0    at Source)    at Source) while locating<> annotated with for parameter 0     at<init>(Unknown Source) while locating 1 error    at$2.get (    at (    at<init> (    at<init> (    at (    at org.forgerock.openam.amster.loadster.EntityTypeProvider.<init> (EntityTypeProvider.groovy:50)    at org.forgerock.openam.amster.loadster.exporter.EntityExporter.<init> (EntityExporter.groovy:47)    at org.forgerock.openam.amster.commands.ExportCommand.execute (ExportCommand.groovy:61)    at org.forgerock.openam.amster.Main$_addCommandLineWrapping_closure2.doCall (Main.groovy:90)    at java_lang_Runnable$ (Unknown Source)    at org.forgerock.openam.amster.Main.main (Main.groovy:60)
  • ERROR Guice provision errors: [main] ERROR org.forgerock.openam.sdk.http.DefaultErrorHandler - Unhandled server error: [Status: 502 Bad Gateway] ERROR  Guice provision errors:  1) Error in custom provider, org.forgerock.openam.sdk.http.ServerErrorException: 502 Bad Gateway     at org.forgerock.openam.sdk.controller.SDKGuiceModule.getHttpSession(Unknown Source)     at org.forgerock.openam.sdk.controller.SDKGuiceModule.getHttpSession(Unknown Source)     while locating org.forgerock.openam.sdk.http.HttpSession     at org.forgerock.openam.sdk.controller.SDKGuiceModule.getCrestResourceProviderForPolicy(Unknown Source)     while locating org.forgerock.openam.sdk.crest.CrestResourceProvider<org.forgerock.openam.sdk.domain.model.Policy> annotated with     for parameter 0 at org.forgerock.openam.sdk.policy.operations.PolicyOperationsProvider.<init>(Unknown Source)     while locating org.forgerock.openam.sdk.policy.operations.PolicyOperationsProvider

Recent Changes



The cause depends on the error seen:

  • ERROR org.forgerock.openam.sdk.http.ServerErrorException

A REST call to the AM server is not serviced within the read-timeout. This timeout defaults to 10 seconds, which should be sufficient in a working environment; this error usually indicates an unresponsive AM server.


This error (with or without the Guice provision errors) indicates an underlying issue with the SSL connection and certificate.


This issue can be resolved as follows depending on the error seen:

ERROR org.forgerock.openam.sdk.http.ServerErrorException

Address the reason(s) why the AM server is unresponsive. If the unresponsiveness is associated with high CPU, see How do I collect data for troubleshooting high CPU utilization on AM (All versions) servers? for further information.

Other possible reasons include network and storage bottlenecks on the AM server, which you should investigate and resolve as needed.

You can also increase the read-timeout when you connect to Amster using the -t (--connection-timeout) option, for example:

am> connect -i -t 30

Which increases the timeout to 30 seconds.


Enable SSL debugging and set the debug level to TRACE to identify the specific cause of your SSL connection issue and resolve accordingly. See How do I enable debug mode for troubleshooting Amster (All versions)? for information on enabling SSL debug logging and increasing the debug level.

Some possible errors that you might encounter include:

Error Resolution Certificate for <host> doesn't match any of the subject alternative names: [SAN] Ensure the hostname is specified in the CN or SAN of the server certificate. Certificate chaining error Ensure the client or server is sending a valid certificate chain with the certificates in the correct order. See SSL client certificate is failing with "ValidatorException: Certificate chaining error" for further information.

See Connect to AM for further information on how Amster connects to an AM instance over the HTTPS protocol.

See Also

FAQ: Installing and using Amster in AM

How do I enable debug mode for troubleshooting Amster (All versions)?

How do I diagnose a hung AM (All versions) server?

Troubleshooting AM and Agents

Using Amster in AM

Amster User guide

Related Training


Related Issue Tracker IDs

OPENAM-11773 (amster throws missleading error '502 bad gateway')

Copyright and Trademarks Copyright © 2023 ForgeRock, all rights reserved.