{"record":{"id":"3f4b50f24f857e24","repo":"chinabugotech/hutool","slug":"unsupport-reference-type","errorCode":null,"errorMessage":"Unsupport Reference type: {}","messagePattern":"Unsupport Reference type: (.+?)","errorType":"exception","errorClass":"UnsupportedOperationException","httpStatus":null,"severity":"error","filePath":"hutool-core/src/main/java/cn/hutool/core/convert/impl/ReferenceConverter.java","lineNumber":53,"sourceCode":"\tprotected Reference<?> convertInternal(Object value) {\n\n\t\t//尝试将值转换为Reference泛型的类型\n\t\tObject targetValue = null;\n\t\tfinal Type paramType = TypeUtil.getTypeArgument(targetType);\n\t\tif(false == TypeUtil.isUnknown(paramType)){\n\t\t\ttargetValue = ConverterRegistry.getInstance().convert(paramType, value);\n\t\t}\n\t\tif(null == targetValue){\n\t\t\ttargetValue = value;\n\t\t}\n\n\t\tif(this.targetType == WeakReference.class){\n\t\t\treturn new WeakReference(targetValue);\n\t\t}else if(this.targetType == SoftReference.class){\n\t\t\treturn new SoftReference(targetValue);\n\t\t}\n\n\t\tthrow new UnsupportedOperationException(StrUtil.format(\"Unsupport Reference type: {}\", this.targetType.getName()));\n\t}\n\n}\n","sourceCodeStart":35,"sourceCodeEnd":57,"githubUrl":"https://github.com/chinabugotech/hutool/blob/8870454b2a0c29cc6ffd31dcf5667c8ceb2fc442/hutool-core/src/main/java/cn/hutool/core/convert/impl/ReferenceConverter.java#L35-L57","documentation":"Thrown by ReferenceConverter.convertInternal() when the target Reference subclass is neither WeakReference nor SoftReference. The converter explicitly only instantiates those two; any other Reference subtype (e.g., PhantomReference or a custom Reference subclass) falls through to UnsupportedOperationException.","triggerScenarios":"Calling Convert.convert(PhantomReference.class, value). Registering a custom Reference subclass type and routing it through the default ReferenceConverter. Passing a user-defined class extending Reference<T> as the conversion target.","commonSituations":"Using PhantomReference in cache or resource-tracking code and attempting Hutool conversion. Custom Reference subclasses for specialized cleanup logic. Generic framework code that converts into any Reference subtype selected at runtime.","solutions":["For PhantomReference or custom Reference types, construct the instance manually: new PhantomReference<>(value, queue).","If you only need WeakReference or SoftReference, ensure the target type is exactly those classes.","Register a custom Converter for your Reference subtype in ConverterRegistry to handle it before the default ReferenceConverter.","Avoid routing arbitrary Reference subtypes through Convert.convert(); construct them directly."],"exampleFix":"// before\nConvert.convert(PhantomReference.class, myObject); // throws\n\n// after\nReferenceQueue<Object> queue = new ReferenceQueue<>();\nPhantomReference<Object> ref = new PhantomReference<>(myObject, queue);","handlingStrategy":"type-guard","validationCode":"if (targetType != WeakReference.class && targetType != SoftReference.class) {\n    // construct manually instead of using the converter\n    throw new UnsupportedOperationException(\"Use manual construction for \" + targetType);\n}\nConvert.convert(targetType, value);","typeGuard":"static boolean isSupportedReferenceType(Class<? extends Reference> type) {\n    return type == WeakReference.class || type == SoftReference.class;\n}","tryCatchPattern":"try {\n    return Convert.convert(targetType, value);\n} catch (UnsupportedOperationException e) {\n    // manually construct unsupported Reference type\n    return targetType.getConstructor(Object.class).newInstance(value);\n}","preventionTips":["Only route WeakReference and SoftReference through Convert.convert().","Construct PhantomReference or custom Reference types directly with new.","Register a custom converter for non-standard Reference subtypes."],"tags":["convert","reference","phantomreference","unsupported-operation"],"backgroundTag":null,"analyzedSha":"8870454b2a0c29cc6ffd31dcf5667c8ceb2fc442","analyzedAt":"2026-08-14T04:01:12.892Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}