{"record":{"id":"b315540efb6df776","repo":"thingsboard/thingsboard","slug":"unsupported-upgrade-method-for-edge","errorCode":null,"errorMessage":"Unsupported upgrade method for Edge: {}","messagePattern":"Unsupported upgrade method for Edge: (.+?)","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":400,"severity":"error","filePath":"application/src/main/java/org/thingsboard/server/service/edge/instructions/DefaultEdgeUpgradeInstructionsService.java","lineNumber":60,"sourceCode":"    private static final Map<String, EdgeUpgradeInfo> upgradeVersionHashMap = new HashMap<>();\n\n    private static final String UPGRADE_DIR = \"upgrade\";\n\n    private final AttributesService attributesService;\n\n    public DefaultEdgeUpgradeInstructionsService(AttributesService attributesService, InstallScripts installScripts) {\n        super(installScripts);\n        this.attributesService = attributesService;\n    }\n\n    @Override\n    public EdgeInstructions getUpgradeInstructions(String edgeVersion, String upgradeMethod) {\n        String currentEdgeVersion = convertEdgeVersionToDocsFormat(edgeVersion);\n        return switch (upgradeMethod.toLowerCase()) {\n            case \"docker\" -> getDockerUpgradeInstructions(this.platformEdgeVersion, currentEdgeVersion);\n            case \"ubuntu\", \"centos\" ->\n                    getLinuxUpgradeInstructions(this.platformEdgeVersion, currentEdgeVersion, upgradeMethod.toLowerCase());\n            default -> throw new IllegalArgumentException(\"Unsupported upgrade method for Edge: \" + upgradeMethod);\n        };\n    }\n\n    @Override\n    public void updateInstructionMap(Map<String, EdgeUpgradeInfo> map) {\n        for (String key : map.keySet()) {\n            upgradeVersionHashMap.put(key, map.get(key));\n        }\n    }\n\n    @Override\n    public boolean isUpgradeAvailable(TenantId tenantId, EdgeId edgeId) throws Exception {\n        Optional<AttributeKvEntry> attributeKvEntryOpt = attributesService.find(tenantId, edgeId, AttributeScope.SERVER_SCOPE, DataConstants.EDGE_VERSION_ATTR_KEY).get();\n        if (attributeKvEntryOpt.isPresent()) {\n            String edgeVersionFormatted = convertEdgeVersionToDocsFormat(attributeKvEntryOpt.get().getValueAsString());\n            return isVersionGreaterOrEqualsThan(edgeVersionFormatted, \"3.6.0\") && !isVersionGreaterOrEqualsThan(edgeVersionFormatted, platformEdgeVersion);\n        }\n        return false;","sourceCodeStart":42,"sourceCodeEnd":78,"githubUrl":"https://github.com/thingsboard/thingsboard/blob/45c30e83fa57356840d5f25d894002d94222d524/application/src/main/java/org/thingsboard/server/service/edge/instructions/DefaultEdgeUpgradeInstructionsService.java#L42-L78","documentation":"IllegalArgumentException from DefaultEdgeUpgradeInstructionsService.getUpgradeInstructions: an unsupported upgrade method was requested. Like installation, only 'docker', 'ubuntu', and 'centos' are accepted (case-insensitive); any other upgradeMethod string falls to the default branch and throws.","triggerScenarios":"GET /api/edge/instructions/upgrade?method=<value> with a value outside docker/ubuntu/centos; UI upgrade dialog sending a legacy or future method id; parameter typo or wrong casing locale ('Docker ' with trailing space); automation scripts hitting the endpoint with a hardcoded method that this backend version renamed.","commonSituations":"Front-end/back-end version skew after a partial upgrade; scripts written against a different ThingsBoard release where the method list differed; copy-pasted curl commands with an edited method parameter.","solutions":["Pass exactly one of: docker, ubuntu, centos","Verify front-end and back-end are the same ThingsBoard release so the method list matches","Trim and normalize the parameter before sending; check for URL-encoding artifacts","For custom upgrade flows, call the docker or linux instruction endpoint and adapt, rather than inventing a method id"],"exampleFix":"// before\nString method = \"helm\"; // not supported\nEdgeInstructions instr = service.getUpgradeInstructions(edgeVersion, method);\n\n// after\nString method = \"docker\";\nEdgeInstructions instr = service.getUpgradeInstructions(edgeVersion, method);","handlingStrategy":"validation","validationCode":"private static final Set<String> SUPPORTED_UPGRADE = Set.of(\"docker\", \"ubuntu\", \"centos\");\nString method = requestedMethod.trim().toLowerCase();\nif (!SUPPORTED_UPGRADE.contains(method)) {\n    // surface a friendly error before calling the API\n}","typeGuard":"static boolean isSupportedUpgradeMethod(String m) {\n    return m != null && Set.of(\"docker\", \"ubuntu\", \"centos\").contains(m.trim().toLowerCase());\n}","tryCatchPattern":null,"preventionTips":["Validate upgrade method against the supported set before the call","Keep UI and backend on the same release","Avoid hardcoding method ids in scripts across version upgrades"],"tags":["edge","upgrade","validation","thingsboard"],"backgroundTag":null,"analyzedSha":"45c30e83fa57356840d5f25d894002d94222d524","analyzedAt":"2026-08-14T11:45:36.599Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}