Troubleshooting Guide

This guide explains how to determine, diagnose, and fix issues you might encounter when using Instance Manager.

Known Issues

View the known issues and possible workarounds in the NGINX Management Suite modules:

Instance Manager

New NGINX instances don't show up in Instance Manager


After installing NGINX and the NGINX Agent on an instance, the instance is not returned when calling GET https://hostname/api/platform/v1/systems.


The NGINX service must be running before you start the NGINX Agent.

  • To resolve the issue, try restarting the NGINX Agent:

    sudo systemctl restart nginx-agent
(RHEL 8) NGINX doesn't start after upgrading NGINX OSS


In some cases, after upgrading NGINX OSS on RHEL 8, the NGINX service may not start and returns an error similar to the following:

Job for nginx.service failed because the control process exited with error code.

The error log may include entries similar to the following example:

022/05/12 16:11:23 [emerg] 69688#69688: still could not bind()
22022/05/12 16:18:34 [emerg] 70092#70092: bind() to failed (98: Address already in use)


Ensure there isn’t a process bound to port 80 or 443.

  1. To stop processes bound to ports 80 and 443, run the following commands:

    sudo fuser -k 80/tcp
    sudo fuser -k 443/tcp
  2. Restart the NGINX service:

    sudo service nginx restart
Scan reports NGINX versions as `undefined` when NGINX App Protect is enabled


When scanning for NGINX instances, the NGINX version is reported as undefined when NGINX App protect is installed.


This behavior is by design. As a security precaution when NGINX App Protect is installed, the NGINX server does not report its version in any HTTP headers. The NGINX Plus and Instances pages in the web interface will continue to report the NGINX and NGINX App Protect versions.

API Connectivity Manager

System returns `403 Forbidden` errors when users try accessing authorized resources


Users are unable to access ACM features that they’ve been granted permission for.

The system returns errors similar to the following examples:

  • Web interface error: “ACM license not found.”

  • API error: “Error accessing resource: forbidden. Please contact the system administrator. User has not been granted READ permission.”


New roles require a minimum of READ access for the Licensing feature. Without READ access for Licensing, users will be unable to access pages for which they have been granted permission; instead, the system will return 403 Forbidden errors as licensing errors.

After installing ACM, the module doesn't show up in the NMS web interface


After installing the API Connectivity Manager module, the module doesn’t appear in the NGINX Management Suite web interface.


  • Force refresh the web page.

  • Restart the ACM service:

    sudo systemctl restart nms-acm
Can't delete ACM objects after upgrading NGINX instances


After upgrading NGINX Plus instances to R27, you may not be able to delete Environments, Proxies, or Dev Portals in the API Connectivity Manager module.


Try restarting the NGINX Agent after upgrading NGINX.

  • To restart the NGINX Agent, run the following command:

    sudo systemctl restart nginx-agent
NGINX Agent doesn't reconnect after a containerized Instance Manager without persistent volumes restarts


If Instance Manager restarts, and there are no persistent volumes configured, then the NGINX Agent won’t automatically reconnect after Instance Manager starts up again.


If a restart of Instance Manager occurs, then a different IP address may be assigned to Instance Manager’s internal API gateway.

To fix the configuration following a restart, you need to update the Instance Manager IP address. To do so, you can either run NGINX Agent with the --server-host CLI parameter or edit the nginx-agent.conf file. Using the --server-host CLI parameter will persist the Agent host setting for the Instance Manager IP address across restarts.

To learn more, check out the NGINX Agent documentation

Security Monitoring

Total requests count is zero on the Security Monitoring dashboard, but there's been a valid attack


For the Security Monitoring module to gather the total request count processed by NGINX, the following requirements must be enabled:

  • The NGINX Plus API must be enabled
  • Each server block that has NGINX App Protect enabled must have status_zone enabled


You can find steps for enabling these requirements in the installation guide for the Security Monitoring module.

Total attack count is greater than total requests processed by NGINX


In some cases, multiple attacks may be logged for a single request sent to NGINX.

This happens if NGINX App Protect WAF is enabled at the server block for content proxied content using proxy_pass.


When configuring NGINX App Protect WAF, make sure to enable app_protect_enable in a proxy_pass location. If the configuration returns static content, add a location that enables NGINX App Protect and proxies the request using proxy_pass to the internal static content location.

Example config

load_module modules/;

http {
    server {
        server_name  localhost;
        status_name  default_server

        location / {
            app_protect_enable on;

        location /proxy {
            default_type text/html;
            return 200 "Hello! I got your URI request - $request_uri\n";

How To Look Up the Installed Version

To see which version of an NGINX Management Suite module is installed, run the following commands:

  • Look up the installed version of Instance Manager:

    yum info nms-instance-manager
  • Look up the installed version of API Connectivity Manager:

    yum info nms-api-connectivity-manager
  • Look up the installed version of the Security Monitoring module:

    yum info nms-sm

  • Look up the installed version of Instance Manager:

    dpkg -s nms-instance-manager
  • Look up the installed version of API Connectivity Manager:

    dpkg -s nms-api-connectivity-manager
  • Look up the installed version of the Security Monitoring module:

    dpkg -s nms-sm