{"record":{"id":"ac546f0c528edd8c","repo":"floci-io/floci","slug":"instancenamerequiredexception","errorCode":"InstanceNameRequiredException","errorMessage":"On-premises instance not found: ${instanceName}","messagePattern":"On-premises instance not found: (.+?)","errorType":"exception","errorClass":"AwsException","httpStatus":400,"severity":"error","filePath":"src/main/java/io/github/hectorvent/floci/services/codedeploy/CodeDeployService.java","lineNumber":752,"sourceCode":"            }\n        }\n        persistRegion(onPremisesInstances, region);\n    }\n\n    public void removeTagsFromOnPremisesInstances(String region, List<String> instanceNames, List<Map<String, String>> tagsToRemove) {\n        for (String name : instanceNames) {\n            OnPremisesInstance inst = requireOnPremisesInstance(region, name);\n            for (Map<String, String> t : tagsToRemove) {\n                inst.getTags().removeIf(e -> e.get(\"Key\").equals(t.get(\"Key\")));\n            }\n        }\n        persistRegion(onPremisesInstances, region);\n    }\n\n    private OnPremisesInstance requireOnPremisesInstance(String region, String instanceName) {\n        OnPremisesInstance inst = onPremisesFor(region).get(instanceName);\n        if (inst == null) {\n            throw new AwsException(\"InstanceNameRequiredException\",\n                    \"On-premises instance not found: \" + instanceName, 400);\n        }\n        return inst;\n    }\n\n    // ---- Server Platform Deployment ----\n\n    private String createServerDeployment(String region, String appName, String groupName,\n                                          DeploymentGroup group, String configName,\n                                          Map<String, Object> revision, String description) {\n        ServerAppSpecInfo appSpec = parseServerAppSpec(revision);\n        String effectiveConfig = configName != null ? configName : group.getDeploymentConfigName();\n\n        String deploymentId = generateDeploymentId();\n        double now = Instant.now().toEpochMilli() / 1000.0;\n\n        Deployment deployment = new Deployment();\n        deployment.setDeploymentId(deploymentId);","sourceCodeStart":734,"sourceCodeEnd":770,"githubUrl":"https://github.com/floci-io/floci/blob/62ff490619e7bd3554597c28c704081b4c15add5/src/main/java/io/github/hectorvent/floci/services/codedeploy/CodeDeployService.java#L734-L770","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","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."],"exampleFix":"// before\nclient.remove_tags_from_on_premises_instances(\n    instanceNames=['web-01'],\n    tags=[{'Key': 'env'}],\n)\n\n// after (verify registration first)\nregistered = client.list_on_premises_instances()['instanceNames']\nif 'web-01' not in registered:\n    client.register_on_premises_instance(instanceName='web-01')\nclient.remove_tags_from_on_premises_instances(\n    instanceNames=['web-01'],\n    tags=[{'Key': 'env'}],\n)","handlingStrategy":"validation","validationCode":"registered = set(client.list_on_premises_instances()['instanceNames'])\nmissing = [n for n in instance_names if n not in registered]\nif missing:\n    raise RuntimeError(f'instances not registered: {missing}')\nclient.remove_tags_from_on_premises_instances(\n    instanceNames=instance_names, tags=[{'Key': 'env'}])","typeGuard":null,"tryCatchPattern":"try:\n    client.remove_tags_from_on_premises_instances(...)\nexcept client.exceptions.InstanceNameRequiredException as e:\n    if 'not found' not in str(e):\n        raise\n    logger.warning('instance missing, re-registering: %s', e)","preventionTips":["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."],"tags":["codedeploy","on-premises","tags","validation","emulator-parity"],"backgroundTag":null,"analyzedSha":"62ff490619e7bd3554597c28c704081b4c15add5","analyzedAt":"2026-08-14T14:25:23.764Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}