floci-io/floci · warning · AwsException

InvalidNextToken

InvalidNextToken

Error message

The NextToken value is not valid.

What it means

Thrown by describeInstanceRefreshes when the NextToken encodes an offset past the end of the filtered result list. Floci represents pagination tokens as integer offsets; a token whose offset exceeds the number of matching refreshes is stale or fabricated, so it returns InvalidNextToken (HTTP 400) the same way AWS rejects expired tokens.

Source

Thrown at src/main/java/io/github/hectorvent/floci/services/autoscaling/AutoScalingService.java:511

            instanceRefreshes.put(instanceRefreshKey(region, asgName, refresh.getInstanceRefreshId()), refresh);
        }
    }

    public InstanceRefreshPage describeInstanceRefreshes(String region, String asgName, List<String> refreshIds,
                                                          Integer maxRecords, String nextToken) {
        requireGroup(region, asgName);
        int offset = parseNextToken(nextToken);
        int limit = maxRecords != null ? Math.min(Math.max(maxRecords, 1), 100) : 50;
        Set<String> requestedIds = refreshIds != null && !refreshIds.isEmpty()
                ? new HashSet<>(refreshIds) : null;
        List<InstanceRefresh> matches = instanceRefreshes.values().stream()
                .filter(r -> region.equals(r.getRegion()))
                .filter(r -> asgName.equals(r.getAutoScalingGroupName()))
                .filter(r -> requestedIds == null || requestedIds.contains(r.getInstanceRefreshId()))
                .sorted(Comparator.comparing(InstanceRefresh::getStartTime).reversed())
                .collect(Collectors.toList());
        if (offset > matches.size()) {
            throw new AwsException("InvalidNextToken", "The NextToken value is not valid.", 400);
        }
        int end = Math.min(offset + limit, matches.size());
        String followingToken = end < matches.size() ? String.valueOf(end) : null;
        return new InstanceRefreshPage(matches.subList(offset, end), followingToken);
    }

    // ── Load balancer attachment ───────────────────────────────────────────────

    public void attachLoadBalancerTargetGroups(String region, String name, List<String> tgArns) {
        AutoScalingGroup asg = requireGroup(region, name);
        for (String arn : tgArns) {
            if (!asg.getTargetGroupARNs().contains(arn)) {
                asg.getTargetGroupARNs().add(arn);
            }
        }
        groups.put(asgKey(region, name), asg);
    }

View on GitHub (pinned to 62ff490619)

Solutions

  1. Restart pagination from the first page (omit NextToken) when this error arrives
  2. Keep the filter parameters (ASG name, InstanceRefreshIds, MaxRecords) identical across paged calls
  3. Don't persist NextToken values across long-lived sessions; treat tokens as short-lived cursors
Defensive patterns

Strategy: try-catch

Try / catch

catch (InvalidNextTokenException e) { restart listing from page 1 without NextToken; }

Prevention

When it happens

Trigger: Calling DescribeInstanceRefreshes with a NextToken obtained from an earlier page after refreshes were deleted or the list shrank; reusing a token from a different ASG or filter set (InstanceRefreshIds); manually crafting a token value.

Common situations: Resuming pagination long after the first page in slow batch jobs; concurrent cleanup deleting refresh history between pages; passing an empty-but-nonnull token string of digits like '999'.

Related errors

AI-assisted analysis of floci-io/floci@62ff490619 (2026-08-14). Data as JSON: /api/errors/df4c8abffb392d6b. Report an issue: GitHub.