
How I fixed missing drift results in the AWS CDK CLI
How a missing pagination loop let `cdk drift --fail` pass on a drifted stack, and how I fixed it in AWS CDK CLI PR #2028 with regression tests, review feedback, and independent validation against CloudFormation.
When
cdk drift --fail is part of a CI pipeline, its exit code matters. A successful command can allow the pipeline to continue even when someone has changed infrastructure outside CloudFormation.That was the problem behind AWS CDK CLI issue #2026 . CloudFormation had detected drift, but the CLI read only the first page of resource results. If the changed resource appeared later, the command could report no drift and exit successfully.
I fixed the result retrieval in PR #2028 , which merged on October 15, 2026. This article walks through the failure, the pagination change, and the evidence used to validate it.
The missing resource was on page two
The issue reporter, LLlnak, provided a concrete example: a stack containing 136
AWS::SSM::Parameter resources plus CDK metadata. One parameter had been deleted outside CloudFormation.The drift results arrived in two pages:
- Page one contained 100
IN_SYNCrecords and a continuation token.
- Page two contained 35
IN_SYNCrecords and oneDELETEDrecord.
The CLI consumed page one, printed
No drift detected , counted 36 resources as unchecked, and returned exit code 0 with --fail . Meanwhile, CloudFormation reported the stack as DRIFTED .The unchecked count was an important clue. Those 36 resources had drift records, but the CLI had never fetched them.
Why the exit code was wrong
The retrieval code lives in
packages/@aws-cdk/toolkit-lib/lib/api/drift/drift.ts . Its detectStackDrift() function starts detection, waits for completion, and retrieves the resource-level results.Before the fix, the retrieval step was a single call:
const driftResults = await cfn.describeStackResourceDrifts({ StackName: stackName,}); CloudFormation's API documentation defines a maximum
MaxResults value of 100 and a NextToken for retrieving subsequent results. The original code never followed that token.The incomplete list then reached
DriftFormatter . It counted returned MODIFIED and DELETED records as drifted and treated template resources without a matching record as unchecked. With only the first page available, it had no deleted resource to count.The CLI's existing exit-code logic returned
1 only when the drift count was positive and --fail was enabled. The pagination bug therefore affected both the displayed result and the pipeline outcome.Completing retrieval before interpreting results
I added pagination inside
detectStackDrift() , before its UNKNOWN -status diagnostics and before the formatter receives the results.const driftResults = await cfn.describeStackResourceDrifts({ StackName: stackName,});
while (driftResults.NextToken) { const page = await cfn.describeStackResourceDrifts({ StackName: stackName, NextToken: driftResults.NextToken, }); driftResults.StackResourceDrifts = [ ...(driftResults.StackResourceDrifts ?? []), ...(page.StackResourceDrifts ?? []), ]; driftResults.NextToken = page.NextToken;}Each request uses the preceding response's token. Its records are appended in page order, and the token is replaced with the next response's value. Once there is no continuation token, retrieval is complete.
Two details matter here. First, the loop follows the token even when a page's resource list is empty or omitted. An empty list cannot establish that pagination has finished.
Second, the code preserves all returned statuses. Later-page
UNKNOWN records still reach the existing diagnostics and unchecked-resource handling; they are not reclassified as confirmed drift. A later-page API error also propagates naturally because the loop does not catch it and return partial results.For a single-page response, the loop does not run. The production change adds ten lines without changing command options, formatting rules, or IAM permissions.
Review made the implementation smaller
My initial implementation used a separate
nextToken variable, conditionally copied the first array, appended with a non-null assertion, and deleted the old token afterward.LLlnak suggested following an existing repository pattern : use the response object's own token and merge each page back into that object. Maintainer mrgrain asked me to apply the suggestion, and I incorporated it in the second commit.
The final version removes that extra bookkeeping while preserving the behavior. The last assignment replaces the previous token with the final page's value, so the result does not retain an obsolete continuation token. The regression tests remained unchanged through the simplification.
Testing the failure path and the edge cases
The pagination test deliberately uses three pages: 100 in-sync records, an empty intermediate page, and finally deleted and unknown records. It runs twice, with the intermediate list represented as
[] and as undefined .The assertions check the complete result order, all three request arguments, the final undefined token, and trace output containing the unknown resource's reason. Another test makes the second request reject and verifies that the same error reaches the caller.
An action-level regression test checks the visible consequence: a deleted bucket returned on a later page produces one drifted resource, zero unchecked resources, and a
Deleted Resources section.My PR records 33 passing drift API/action tests, two passing existing CLI exit-code tests, successful TypeScript compilation, and clean lint. These used mocked AWS responses; I did not perform a live deployment for that validation. The final PR head also had a successful build workflow .
Independent validation against CloudFormation
LLlnak then tested the branch against the real stack . Their comparison showed
aws-cdk@2.1144.0 reporting zero drift and exiting 0 , while the PR branch reported the deleted parameter, counted one drifted resource, and exited 1 .They also reported the same live result with the simplified implementation. That provided independent end-to-end evidence alongside the mocked regression tests.
What this fixes
The fix ensures that downstream drift reporting receives every page returned by CloudFormation. CloudFormation's resource-support and detection limitations still apply; pagination cannot make an unsupported resource checkable.
As of October 15, 2026, the change is merged. The latest GitHub-listed CLI release, 2.1145.0 , predates the merge and does not include it.
The practical lesson is to test the boundary between retrieval and interpretation. For a paginated API, a correct first response is only part of the answer. When that answer controls an exit code, completeness needs explicit regression coverage.
Enjoyed reading this content? Let the author know!
Your likes, comments, shares, and saves help creators reach more builders.
Loading recommendations
Loading article