thingsboard/thingsboard · error · IllegalArgumentException

Unsupported upgrade method for Edge: {}

Error message

Unsupported upgrade method for Edge: {}

What it means

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.

Source

Thrown at application/src/main/java/org/thingsboard/server/service/edge/instructions/DefaultEdgeUpgradeInstructionsService.java:60

    private static final Map<String, EdgeUpgradeInfo> upgradeVersionHashMap = new HashMap<>();

    private static final String UPGRADE_DIR = "upgrade";

    private final AttributesService attributesService;

    public DefaultEdgeUpgradeInstructionsService(AttributesService attributesService, InstallScripts installScripts) {
        super(installScripts);
        this.attributesService = attributesService;
    }

    @Override
    public EdgeInstructions getUpgradeInstructions(String edgeVersion, String upgradeMethod) {
        String currentEdgeVersion = convertEdgeVersionToDocsFormat(edgeVersion);
        return switch (upgradeMethod.toLowerCase()) {
            case "docker" -> getDockerUpgradeInstructions(this.platformEdgeVersion, currentEdgeVersion);
            case "ubuntu", "centos" ->
                    getLinuxUpgradeInstructions(this.platformEdgeVersion, currentEdgeVersion, upgradeMethod.toLowerCase());
            default -> throw new IllegalArgumentException("Unsupported upgrade method for Edge: " + upgradeMethod);
        };
    }

    @Override
    public void updateInstructionMap(Map<String, EdgeUpgradeInfo> map) {
        for (String key : map.keySet()) {
            upgradeVersionHashMap.put(key, map.get(key));
        }
    }

    @Override
    public boolean isUpgradeAvailable(TenantId tenantId, EdgeId edgeId) throws Exception {
        Optional<AttributeKvEntry> attributeKvEntryOpt = attributesService.find(tenantId, edgeId, AttributeScope.SERVER_SCOPE, DataConstants.EDGE_VERSION_ATTR_KEY).get();
        if (attributeKvEntryOpt.isPresent()) {
            String edgeVersionFormatted = convertEdgeVersionToDocsFormat(attributeKvEntryOpt.get().getValueAsString());
            return isVersionGreaterOrEqualsThan(edgeVersionFormatted, "3.6.0") && !isVersionGreaterOrEqualsThan(edgeVersionFormatted, platformEdgeVersion);
        }
        return false;

View on GitHub (pinned to 45c30e83fa)

Solutions

  1. Pass exactly one of: docker, ubuntu, centos
  2. Verify front-end and back-end are the same ThingsBoard release so the method list matches
  3. Trim and normalize the parameter before sending; check for URL-encoding artifacts
  4. For custom upgrade flows, call the docker or linux instruction endpoint and adapt, rather than inventing a method id

Example fix

// before
String method = "helm"; // not supported
EdgeInstructions instr = service.getUpgradeInstructions(edgeVersion, method);

// after
String method = "docker";
EdgeInstructions instr = service.getUpgradeInstructions(edgeVersion, method);
Defensive patterns

Strategy: validation

Validate before calling

private static final Set<String> SUPPORTED_UPGRADE = Set.of("docker", "ubuntu", "centos");
String method = requestedMethod.trim().toLowerCase();
if (!SUPPORTED_UPGRADE.contains(method)) {
    // surface a friendly error before calling the API
}

Type guard

static boolean isSupportedUpgradeMethod(String m) {
    return m != null && Set.of("docker", "ubuntu", "centos").contains(m.trim().toLowerCase());
}

Prevention

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of thingsboard/thingsboard@45c30e83fa (2026-08-14). Data as JSON: /api/errors/b315540efb6df776. Report an issue: GitHub.