After an application is restarted or redeployed, the Nacos console may show the application as offline even though it is healthy. This happens because the enabled field on the registered instance is set to false.
By default, the enabled field is true when an application registers with Nacos. If the field shows false after a restart, either the application explicitly set it during registration, or Nacos reused stale metadata from a previous instance.
Causes
The application registers with
enabled=false. The application code or configuration explicitly sets theenabledfield tofalseduring registration.Nacos reuses stale metadata from the previous instance. During shutdown, the previous instance called the Nacos OpenAPI V1 modify instance operation or OpenAPI V2 update instance operation to set
enabledtofalse. Nacos retains this metadata for up to 1 minute. If the new instance registers with the same IP address and port within that window, Nacos reuses the old metadata, includingenabled=false. The following sequence illustrates this race condition:The old instance stops and calls the modify/update API with
enabled=false.The new instance starts and registers with the same IP and port within 1 minute.
Nacos has not yet cleared the old metadata and applies it to the new registration, including
enabled=false.
Diagnose the root cause
Check the Nacos client logs on the service provider node to determine which cause applies.
Get the Nacos client logs from the node where the service provider is deployed. For more information, see How do I obtain logs from a Nacos client?
Search the logs for the keyword
REGISTER-SERVICEand check the value of theenabledfield in the registration details.If
enabledisfalsein the registration log, the application is explicitly setting it. Go to Fix: application registers withenabled=false.If
enabledistruein the registration log, the issue is caused by stale metadata reuse. Go to Fix: stale metadata reuse after restart.
Fix: application registers with enabled=false
The application or its configuration explicitly sets enabled to false at startup.
Option 1 (Recommended): Fix the registration configuration
Locate where the application sets the enabled field and change the value to true, or remove the setting entirely. The default value is true.
Option 2: Override enabled through the API after startup
If you cannot identify where enabled=false is set, call the Nacos API to set enabled to true after the service provider starts.
Use the modify instance operation in OpenAPI V1:
curl -X PUT 'http://<nacos-host>:8848/nacos/v1/ns/instance?serviceName=<service-name>&ip=<ip>&port=<port>&enabled=true'Or use the update instance operation in OpenAPI V2:
curl -X PUT 'http://<nacos-host>:8848/nacos/v2/ns/instance?serviceName=<service-name>&ip=<ip>&port=<port>&enabled=true'Replace the following placeholders with actual values:
| Placeholder | Description | Example |
|---|---|---|
<nacos-host> | Address of the Nacos server | 192.168.1.100 |
<service-name> | Name of the registered service | com.example.OrderService |
<ip> | IP address of the service provider | 10.0.0.5 |
<port> | Port of the service provider | 8080 |
Fix: stale metadata reuse after restart
The previous instance set enabled=false during shutdown, and the new instance registered with the same IP and port before Nacos cleared the old metadata (within 1 minute).
Option 1 (Recommended): Enable graceful rolling deployment
Remove the logic that calls the modify/update instance API to set enabled=false during application shutdown. Instead, enable the graceful rolling deployment feature of Microservices Governance, which handles instance deregistration and traffic draining automatically.
Option 2: Increase the interval between deregistration and re-registration
Make sure the interval between the time when the service provider is deregistered (or automatically removed) and the time when it re-registers is greater than 1 minute. This gives Nacos enough time to clear the old instance metadata.
Option 3: Reset enabled through the API after startup
After the service provider confirms that it has started, call the Nacos API to set enabled to true. For the API commands and placeholder descriptions, see Option 2: Override enabled through the API after startup.
Verify the fix
After you apply a fix, confirm that the enabled field is true:
Open the Nacos console and locate the service.
Check that the application instance shows as online.
Alternatively, search the Nacos client logs for
REGISTER-SERVICEand verify thatenabledistruein the latest registration entry.
Prevention
To avoid this issue in future deployments:
Use graceful rolling deployment. Enable the graceful rolling deployment feature of Microservices Governance to handle instance lifecycle transitions automatically. This eliminates the need to manually call the modify/update instance API during shutdown.
Do not set
enabled=falseduring shutdown. If your shutdown logic currently calls the Nacos API to disable the instance, remove that call and rely on Microservices Governance for traffic draining.Allow sufficient restart intervals. If you cannot use graceful rolling deployment, make sure at least 1 minute passes between stopping the old instance and starting the new one. Nacos retains instance metadata for up to 1 minute after deregistration, and a new registration within this window inherits the old metadata.