(config): Local deployment cannot override Nucleus `deploymentPollingFrequencySeconds` configuration

[NickDarvey]

Summary

Local deployments using RESET + MERGE operations fail to override the deploymentPollingFrequencySeconds configuration on the Nucleus component, even when using --groupId to target the specific thing group that owns the configuration. The deployment succeeds but the configuration value remains unchanged.

This same approach (RESET + MERGE) works correctly for other components (e.g., custom component accessControl configuration), suggesting special handling or protection of Nucleus configuration that is not documented.

Environment

• Greengrass Nucleus Version: 2.15.0
• OS: Linux (aarch64)
• Region: ap-southeast-2

Steps to Reproduce

Test 1: Local deployment without --groupId

sudo /greengrass/v2/bin/greengrass-cli deployment create \
  --update-config '{
    "aws.greengrass.Nucleus": {
      "RESET": ["/deploymentPollingFrequencySeconds"],
      "MERGE": {
        "deploymentPollingFrequencySeconds": 345600
      }
    }
  }'

Result: Deployment succeeds, but deploymentPollingFrequencySeconds remains 15.

Test 2: Local deployment with --groupId targeting the thing group

sudo /greengrass/v2/bin/greengrass-cli deployment create \
  --groupId thinggroup/MyGroup \
  --update-config '{
    "aws.greengrass.Nucleus": {
      "RESET": ["/deploymentPollingFrequencySeconds"],
      "MERGE": {
        "deploymentPollingFrequencySeconds": 345600
      }
    }
  }'

Result: Deployment succeeds, but deploymentPollingFrequencySeconds remains 15.

Expected Behavior

The deploymentPollingFrequencySeconds should be updated to 345600 (4 days) after either deployment completes successfully.

According to CONFIGURE_COMPONENT_README.md:

"The configuration will first perform RESET and then perform MERGE, regardless of the order they are given in the JSON Object."

The RESET should clear the cloud-configured value, and MERGE should apply the new value.

Actual Behavior

Both deployments complete with SUCCEEDED status, but the Nucleus configuration shows deploymentPollingFrequencySeconds: "15" (unchanged from cloud deployment default).

Logs

Test 1: Without --groupId (Deployment ID: 8ba89165-db22-4fb9-97b6-f7a1ab047cdd)

Deployment document received:

2026-02-09T03:39:18.653Z [INFO] (pool-3-thread-33) com.aws.greengrass.deployment.DeploymentService:
Received deployment document in queue. {document={
  "requestId":"8ba89165-db22-4fb9-97b6-f7a1ab047cdd",
  "requestTimestamp":1770608353003,
  "componentsToMerge":null,
  "componentsToRemove":null,
  "groupName":null,
  "requiredCapabilities":null,
  "componentNameToConfig":null,
  "configurationUpdate":{
    "aws.greengrass.Nucleus":{
      "MERGE":{"deploymentPollingFrequencySeconds":345600.0},
      "RESET":["/deploymentPollingFrequencySeconds"]
    }
  },
  "componentToRunWithInfo":null,
  "recipeDirectoryPath":null,
  "artifactsDirectoryPath":null,
  "failureHandlingPolicy":null
}, serviceName=DeploymentService, currentState=RUNNING}

Deployment completed:

2026-02-09T03:40:25.550Z [INFO] (pool-3-thread-114) com.aws.greengrass.deployment.activator.DeploymentActivator:
merge-config. All services updated. {deploymentId=8ba89165-db22-4fb9-97b6-f7a1ab047cdd}

Post-deployment configuration check:

$ sudo /greengrass/v2/bin/greengrass-cli component details --name aws.greengrass.Nucleus | grep polling
Configuration: {...,"deploymentPollingFrequencySeconds":"15",...}

Test 2: With --groupId (Deployment ID: f727f52b-2027-4dc3-84dd-9c3e41c9c8b1)

Deployment document received:

2026-02-09T05:43:06.057Z [INFO] (pool-3-thread-33) com.aws.greengrass.deployment.DeploymentService:
Received deployment document in queue. {document={
  "requestId":"f727f52b-2027-4dc3-84dd-9c3e41c9c8b1",
  "requestTimestamp":1770615778425,
  "componentsToMerge":null,
  "componentsToRemove":null,
  "groupName":"thinggroup/MyGroup",
  "requiredCapabilities":null,
  "componentNameToConfig":null,
  "configurationUpdate":{
    "aws.greengrass.Nucleus":{
      "MERGE":{"deploymentPollingFrequencySeconds":345600.0},
      "RESET":["/deploymentPollingFrequencySeconds"]
    }
  },
  "componentToRunWithInfo":null,
  "recipeDirectoryPath":null,
  "artifactsDirectoryPath":null,
  "failureHandlingPolicy":null
}, serviceName=DeploymentService, currentState=RUNNING}

Config merge applied:

2026-02-09T05:43:39.997Z [INFO] (pool-3-thread-143) com.aws.greengrass.deployment.DeploymentConfigMerger:
merge-config. Applying deployment changes. {deployment=f727f52b-2027-4dc3-84dd-9c3e41c9c8b1}

Deployment completed:

2026-02-09T05:44:11.321Z [INFO] (pool-3-thread-143) com.aws.greengrass.deployment.activator.DeploymentActivator:
merge-config. All services updated. {deploymentId=f727f52b-2027-4dc3-84dd-9c3e41c9c8b1}

2026-02-09T05:44:21.324Z [INFO] (pool-3-thread-33) com.aws.greengrass.deployment.DeploymentStatusKeeper:
Stored deployment status. {DeploymentId=f727f52b-2027-4dc3-84dd-9c3e41c9c8b1, DeploymentStatus=SUCCEEDED}

Post-deployment configuration check:

$ sudo /greengrass/v2/bin/greengrass-cli component details --name aws.greengrass.Nucleus | grep polling
Configuration: {...,"deploymentPollingFrequencySeconds":"15",...}

Comparison: Working Case with Custom Component

For comparison, the same RESET + MERGE approach works correctly for a custom component's accessControl configuration:

Deployment ID: 07b3e9e6-2e78-492c-baf0-8f31a54c6c41

sudo /greengrass/v2/bin/greengrass-cli deployment create \
  --merge "devcontainer=1.0.6647" \
  --update-config '{
    "devcontainer": {
      "RESET": ["/accessControl"],
      "MERGE": {
        "accessControl": {
          "aws.greengrass.Cli": {
            "...:AllowCreateLocalDeployment": {...},
            "...:AllowGetComponentDetails": {...}
          }
        }
      }
    }
  }'

Result: Deployment succeeded AND configuration was updated correctly.

Context

The device belongs to multiple thing groups that depend on the Nucleus component:

• thinggroup/MyGroup (sets deploymentPollingFrequencySeconds: 15)
• thinggroup/MyDevcontainerGroup
• thinggroup/MyOtherGroup

The Nucleus recipe default configuration also specifies:

DefaultConfiguration:
  deploymentPollingFrequencySeconds: "15"

Questions

1. Is there intentional protection preventing local deployments from overriding Nucleus configuration?
2. If so, is this documented anywhere?
3. If not, is this a bug in the configuration merge logic for Nucleus components?
4. What is the recommended approach to temporarily override deploymentPollingFrequencySeconds from a device without modifying cloud deployments?

Use Case

We need to temporarily pause cloud deployment polling during local development/debugging sessions on edge devices, then resume normal polling afterward. The ability to control this via local deployment would be valuable for development workflows.

[patrzhan]

So the current behavior with local deployment (and technically cloud deployments as well) is that configuration is only applied for components that are included as part of that deployment. So in this case even though there is a local deployment that changes configuration for Nucleus, since Nucleus isn't specified as part of that deployment directly those configuration changes do not get applied. Aside from this quirk there wouldn't be any specific protection or behavior that is blocking your configuration update from being processed.

To get your configuration applied you should just add aws.greengrass.Nucleus as a component that is being added to the deployment. You don't need to provide any recipes or artifacts to copy since the device is already running the component, but you just need to specify it for the deployment to actually process the Nucleus component.

I wouldn't call this a bug yet, but it's certainly a quirk. I'm not sure if we have this specific behavior documented somewhere, but I've seen it come up at least one other time.

[NickDarvey]

@patrzhan, so in this case I would need to add a rootComponentVersionsToAdd to the below?

    const response = await client.createLocalDeployment({
      componentToConfiguration: new Map([
        [
          NUCLEUS_COMPONENT,
          {
            MERGE: {
              deploymentPollingFrequencySeconds: pollingSeconds,
            },
          },
        ],
      ]),
    });

My problem with that is I don't want to introduce conflicts if our Nucleus version is bumped (deployed separately). (That is, this local deployment would be pinning the Nucleus version.)

---

Edit: Oh, for my use case, I'm actually pausing deployments so this is fine to pin the Nucleus (until the pause elapses! but oh well). Do I just need to use rootComponentVersionsToAdd?

[patrzhan]

Yup, setting rootComponentVersionsToAdd to include Nucleus should work for what you need. If pinning the Nucleus version to local deployments is an issue in the future you can try working around with setting groupName for the deployment to something that can be updated by cloud later but if it isn't an issue like you said then this should be all you need!

[NickDarvey]

Yup, setting rootComponentVersionsToAdd to include Nucleus should work for what you need.

How would I 'undo' this later then? Can I do another local deployment with 'rootComponentsToRemove', but it'll keep the Nucleus because the cloud has deployed it?

[NickDarvey]

It kinda worked, the configuration got updated, but the deployment is stuck.

Environment

• Greengrass Nucleus: 2.15.0
• Greengrass CLI: 2.16.0

Stuck Deployment Details

• Deployment ID: aac392d8-78ca-44db-aec1-14bf77658d9b
• Created: 2026-02-13 05:02:45 UTC
• Status: IN_PROGRESS (stuck for 5+ hours)
• Intended Change: Set deploymentPollingFrequencySeconds to
  604800 (7 days)

Stuck deployment metadata:

  {
    "Name": "aws.greengrass.Nucleus",
    "RootComponent": true,
    "ResolvedVersion": "2.15.0",
    "ConfigurationUpdate": {
      "MERGE": {"deploymentPollingFrequencySeconds": 604800.0},
      "RESET": null
    }
  }

Timeline from config.tlog

Timestamp	Event
1770958965573	Deployment added to queue (QUEUED)
1770958970518	DeploymentService picked up deployment
1770958970550	Status changed to IN_PROGRESS
1770959005673	Config change applied (deploymentPollingFrequencySeconds=604800.0)
(never)	Status never transitions to SUCCEEDED

Impact

1. The stuck deployment blocks the deployment queue - new
   deployments remain in QUEUED state
2. deployment cancel command has no effect (deployment still
   shows IN_PROGRESS)
3. The ongoing symlink remains pointing to the stuck
   deployment
4. All components are running normally - only the deployment
   status tracking is broken

Current State

• Config was applied: The change to
  deploymentPollingFrequencySeconds was written to config.tlog
• All components running: No component is in BROKEN or ERRORED
  state
• Cancel ineffective: cancelled: false in
  deployment_metadata.json even after cancel command
• Queue blocked: Subsequent deployment
  2170b458-d0e5-4394-bcea-ae1c025d0df5 stuck in QUEUED

[NickDarvey]

@patrzhan, any ideas here?

[patrzhan]

Sorry for the delay. For the first question I think you can have Nucleus in your components to remove and it'll be excluded from your local deployment 'group'. For the stuck deployment, from an initial inspection it would make sense that new deployment remains in queued state because of the very long polling time but it shouldn't be the case (imo) that the current deployment stays in progress. Someone else on our team is taking a look at it and we'll update here soon.

[NickDarvey]

Actually, maybe it was because it was already set to deploymentPollingFrequencySeconds: 604800 it wasn't taking that update. Interestingly, I returned to this two weeks later (604800 = 1 week) and it was still stuck.

Stuck deployment

Field	Value
Deployment ID	aac392d8-78ca-44db-aec1-14bf77658d9b
Created (UTC)	13 Feb 2026 05:02:45
Deployment type	LOCAL
Root packages	aws.greengrass.Cli, aws.greengrass.SecretManager, aws.greengrass.ShadowManager, aws.greengrass.Nucleus
Intended change	CommsboardGroup / infra-components: Nucleus config MERGE deploymentPollingFrequencySeconds: 604800

Current state (as of collection)

1. CLI and effective config

• greengrass-cli deployment list shows aac392d8 with Status: IN_PROGRESS.
• greengrass-cli deployment status -i aac392d8-78ca-44db-aec1-14bf77658d9b reports IN_PROGRESS and creation time only (no error details).
• In effectiveConfig.yaml, under services.aws.greengrass.Cli.runtime.LocalDeployments, aac392d8 is present with:
  • DeploymentStatus: IN_PROGRESS
  • DeploymentStatusDetails: {}
  • DeploymentType: LOCAL
  • No ConfigurationArn (null).

2. Disk state (deployments directory)

• aac392d8 directory: absent (/greengrass/v2/deployments/aac392d8-78ca-44db-aec1-14bf77658d9b/ does not exist).
• ongoing symlink: absent.

So the “in progress” deployment has no on-disk deployment directory and no ongoing symlink.

3. config.tlog (state that drives effectiveConfig)

• LocalDeployments.aac392d8: Added at TS 1770958965573, then status set to QUEUED, then to IN_PROGRESS at TS 1770958970550. No later tlog entry ever sets this deployment to SUCCEEDED, FAILED, or CANCELLED.
• ProcessedDeployments: An entry for this deployment (ProcessedDeployments.1770958970518, GreengrassDeploymentId aac392d8) was added with DeploymentStatus IN_PROGRESS, then removed ("W":"removed"). So DeploymentService dropped this deployment from ProcessedDeployments without recording a terminal status.

Result: CLI/effectiveConfig still show IN_PROGRESS from LocalDeployments, while DeploymentService has no ProcessedDeployments record for this deployment and there is no deployment directory.

4. Cancel attempts

• greengrass-cli deployment cancel -i aac392d8-78ca-44db-aec1-14bf77658d9b was run multiple times.
• Response each time: “Cancel request submitted. Deployment ID: aac392d8-...”
• Status never changed to CANCELLED; it remained IN_PROGRESS.
• No log evidence that the cancel for aac392d8 was actually processed (in /greengrass/v2/logs/greengrass.log)

5. Restart and config-edit workaround

• Restart: systemctl restart greengrass.service was run at least once. After restart, aac392d8 still appeared as IN_PROGRESS; the deployment directory for aac392d8 did not reappear.
• Config edit (to change polling): To work around 7-day polling, the following were edited and Greengrass was restarted:
  • /greengrass/v2/config/config.tlog – last “changed” value for deploymentPollingFrequencySeconds set from 604800 to 15.
  • /greengrass/v2/config/effectiveConfig.yaml – deploymentPollingFrequencySeconds set to 15.
    After that restart, Nucleus correctly applied 15s polling, but aac392d8 remained IN_PROGRESS in the CLI and in effectiveConfig.

Snippets

effectiveConfig.yaml – aac392d8 entry

        aac392d8-78ca-44db-aec1-14bf77658d9b:
          ConfigurationArn: null
          CreatedOn: 1770958965573
          DeploymentId: "aac392d8-78ca-44db-aec1-14bf77658d9b"
          DeploymentRootPackages:
          - "aws.greengrass.Cli"
          - "aws.greengrass.SecretManager"
          - "aws.greengrass.ShadowManager"
          - "aws.greengrass.Nucleus"
          DeploymentStatus: "IN_PROGRESS"
          DeploymentStatusDetails: {}
          DeploymentType: "LOCAL"
          GreengrassDeploymentId: "aac392d8-78ca-44db-aec1-14bf77658d9b"

config.tlog – LocalDeployments and ProcessedDeployments for aac392d8

• LocalDeployments: interiorAdded for aac392d8, then DeploymentStatus QUEUED, then IN_PROGRESS. No later status change.
• ProcessedDeployments.1770958970518: DeploymentId/GreengrassDeploymentId aac392d8, DeploymentStatus IN_PROGRESS, then removed.

Deployments directory listing

drwx------  2 root root 4096 Feb 24 18:32 166d33b2-820a-4203-aa53-9c985638d219
lrwxrwxrwx  1 root root   63 Feb 24 18:33 previous-success -> /greengrass/v2/deployments/166d33b2-820a-4203-aa53-9c985638d219

(No aac392d8 directory, no ongoing symlink.)

[NickDarvey]

I just edit the tlog by appending a new entry using the current timestamp and it seems to have unstuck it.

{"TS":1771920700000,"TP":["services","aws.greengrass.Cli","runtime","LocalDeployments","aac392d8-78ca-44db-aec1-14bf77658d9b"],"W":"removed","V":null}

[NickDarvey]

Alright, just tried this guidance out again, here's a tighter repro of steps.

---

Environment: Nucleus 2.15.0, Linux, ap-southeast-2. Baseline: no local deployments; deploymentPollingFrequencySeconds = 15.

Test 1 — Guidance (add Nucleus + MERGE)
Ran on device:

sudo /greengrass/v2/bin/greengrass-cli deployment create \
  --groupId thinggroup/MyGroup \
  --merge "aws.greengrass.Nucleus=2.15.0" \
  --update-config '{"aws.greengrass.Nucleus":{"MERGE":{"deploymentPollingFrequencySeconds":345600}}}'

CLI output (verbatim):

Local deployment submitted! Deployment Id: a747b8a5-66aa-4b69-9406-abec043b0d57

Result: Config applied: deploymentPollingFrequencySeconds = 345600. Deployment never reached SUCCEEDED; it remains IN_PROGRESS and blocks the queue (same as described in the issue).

deployment list (verbatim, excerpt):

Deployment ID: a747b8a5-66aa-4b69-9406-abec043b0d57
Created on: 24-02-2026 23:49:53 UTC
Status: IN_PROGRESS

Test 2 — Resume via CLI (--remove + --groupId)
To avoid pinning Nucleus to a version, tried --remove with --groupId:

sudo /greengrass/v2/bin/greengrass-cli deployment create \
  --remove "aws.greengrass.Nucleus" \
  --groupId thinggroup/MyGroup

CLI output (verbatim):

Local deployment submitted! Deployment Id: d0cf1fb7-87fe-4c86-8344-c06cca585eb1

greengrass.log (verbatim):

2026-02-25T00:19:18.718Z [INFO] (AwsEventLoop 1) com.aws.greengrass.cli.CLIEventStreamAgent: Submitted local deployment request.. {deploymentId=d0cf1fb7-87fe-4c86-8344-c06cca585eb1}

Result: This deployment stays QUEUED (blocked by the stuck IN_PROGRESS one). After it was submitted, deploymentPollingFrequencySeconds was still 345600 — i.e. --remove alone does not reset the config; it only removes Nucleus from the local deployment group.

component details after Test 2 (verbatim excerpt):

Configuration: {...,"deploymentPollingFrequencySeconds":345600.0,...}

Summary: Guidance works for applying config (add + MERGE → 345600), but the deployment stays IN_PROGRESS and blocks the queue.

[NickDarvey]

I've also tried 'resuming' through this method:

sudo /greengrass/v2/bin/greengrass-cli deployment create \
  --remove "aws.greengrass.Nucleus" \
  --groupId thinggroup/MyGroup \
  --update-config '{"aws.greengrass.Nucleus":{"RESET":["deploymentPollingFrequencySeconds"]}}'

CLI output:

Local deployment submitted! Deployment Id: fce52d0b-8cab-4d54-b25a-60a75307e238

After ~15s and again after ~60s:
Deployment status: QUEUED (unchanged).
deploymentPollingFrequencySeconds: 345600.0 (unchanged).

[archigup]

Yeah, it does look like the deploymentPollingFrequencySeconds blocks local deployments for the interval as well. This will likely need a nucleus fix