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

Last updated May 1, 2020

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)
    [main] ERROR - Unhandled server error: [Status: 502 Bad Gateway]
    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] 
    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/OpenAM (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.

In AM 5.5.2 and later, 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 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/OpenAM (All versions) server?

How do I use the msnapshots script to capture information for troubleshooting AM/OpenAM (All versions)?

Troubleshooting AM/OpenAM and Policy Agents

Using Amster in AM

User Guide

Related Training


Related Issue Tracker IDs

OPENAM-11876 (Amster has a timeout limit of 10 second and it is not configurable )

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

Copyright and TrademarksCopyright © 2020 ForgeRock, all rights reserved.