What causes "On-premises instance not found: ${instanceName}" in floci-io/floci?

Call ListOnPremisesInstances first and verify every name in instanceNames appears in the response before issuing the tag call.

floci-io/floci · error · AwsException

InstanceNameRequiredException

InstanceNameRequiredException

Error message

On-premises instance not found: ${instanceName}

What it means

Thrown by CodeDeployService.requireOnPremisesInstance (line 752) when a tag operation references an on-premises instance name that is not registered in the emulator's regional store. The loop at the call site resolves every entry of instanceNames via onPremisesFor(region).get(name), and any miss aborts before persisting. Note the error code is misleading: real AWS uses InstanceNameRequiredException for a missing instanceNames parameter, while an unknown instance yields InstanceNotRegisteredException.

Source

Thrown at src/main/java/io/github/hectorvent/floci/services/codedeploy/CodeDeployService.java:752

            }
        }
        persistRegion(onPremisesInstances, region);
    }

    public void removeTagsFromOnPremisesInstances(String region, List<String> instanceNames, List<Map<String, String>> tagsToRemove) {
        for (String name : instanceNames) {
            OnPremisesInstance inst = requireOnPremisesInstance(region, name);
            for (Map<String, String> t : tagsToRemove) {
                inst.getTags().removeIf(e -> e.get("Key").equals(t.get("Key")));
            }
        }
        persistRegion(onPremisesInstances, region);
    }

    private OnPremisesInstance requireOnPremisesInstance(String region, String instanceName) {
        OnPremisesInstance inst = onPremisesFor(region).get(instanceName);
        if (inst == null) {
            throw new AwsException("InstanceNameRequiredException",
                    "On-premises instance not found: " + instanceName, 400);
        }
        return inst;
    }

    // ---- Server Platform Deployment ----

    private String createServerDeployment(String region, String appName, String groupName,
                                          DeploymentGroup group, String configName,
                                          Map<String, Object> revision, String description) {
        ServerAppSpecInfo appSpec = parseServerAppSpec(revision);
        String effectiveConfig = configName != null ? configName : group.getDeploymentConfigName();

        String deploymentId = generateDeploymentId();
        double now = Instant.now().toEpochMilli() / 1000.0;

        Deployment deployment = new Deployment();
        deployment.setDeploymentId(deploymentId);

View on GitHub (pinned to 62ff490619)

Solutions

Call ListOnPremisesInstances first and verify every name in instanceNames appears in the response before issuing the tag call.
Register the missing instance with RegisterOnPremisesInstance({instanceName}) and retry the tag operation.
Check the region of your AWS client/CLI matches the region used when the instance was registered.
If the instance was intentionally removed, prune it from your tag-lists so the loop stops referencing it.
Floci maintainers: consider mapping this case to InstanceNotRegisteredException for closer AWS parity.

Example fix

// before
client.remove_tags_from_on_premises_instances(
    instanceNames=['web-01'],
    tags=[{'Key': 'env'}],
)

// after (verify registration first)
registered = client.list_on_premises_instances()['instanceNames']
if 'web-01' not in registered:
    client.register_on_premises_instance(instanceName='web-01')
client.remove_tags_from_on_premises_instances(
    instanceNames=['web-01'],
    tags=[{'Key': 'env'}],
)

Defensive patterns

Strategy: validation

Validate before calling

registered = set(client.list_on_premises_instances()['instanceNames'])
missing = [n for n in instance_names if n not in registered]
if missing:
    raise RuntimeError(f'instances not registered: {missing}')
client.remove_tags_from_on_premises_instances(
    instanceNames=instance_names, tags=[{'Key': 'env'}])

Try / catch

try:
    client.remove_tags_from_on_premises_instances(...)
except client.exceptions.InstanceNameRequiredException as e:
    if 'not found' not in str(e):
        raise
    logger.warning('instance missing, re-registering: %s', e)

Prevention

Maintain the registered-instance list as configuration, derived from ListOnPremisesInstances, not hand-typed names.
Run register + tag in the same script with the same client region.
After DeregisterOnPremisesInstance, remove the name from all tag-management lists the same day.

When it happens

Trigger: Calling AddTagsToOnPremisesInstances or RemoveTagsFromOnPremisesInstances with an instanceNames entry that was never registered via RegisterOnPremisesInstance, or that was deleted via DeregisterOnPremisesInstance, or that was registered in a different region (the lookup is per-region).

Common situations: Scripts that hardcode instance names from another environment; deregistering an instance but leaving stale entries in a CI tag-cleanup job; cross-region confusion because on-premises instances are stored per-region in Floci; IAM-session/region mismatch between register and tag steps.

Related errors

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