{"record":{"id":"2812df1a31146233","repo":"apache/cassandra","slug":"expected-a-string-representation-of-a-timeuuid-bu","errorCode":null,"errorMessage":"Expected a string representation of a timeuuid, but got a %s: %s","messagePattern":"Expected a string representation of a timeuuid, but got a (.+?): (.+?)","errorType":"validation","errorClass":"MarshalException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/db/marshal/AbstractTimeUUIDType.java","lineNumber":176,"sourceCode":"    {\n        ByteBuffer parsed = UUIDType.parse(source);\n        if (parsed == null)\n            throw new MarshalException(String.format(\"Unknown timeuuid representation: %s\", source));\n        if (parsed.remaining() == 16 && UUIDType.version(parsed) != 1)\n            throw new MarshalException(\"TimeUUID supports only version 1 UUIDs\");\n        return parsed;\n    }\n\n    @Override\n    public Term fromJSONObject(Object parsed) throws MarshalException\n    {\n        try\n        {\n            return new Constants.Value(fromString((String) parsed));\n        }\n        catch (ClassCastException exc)\n        {\n            throw new MarshalException(\n                    String.format(\"Expected a string representation of a timeuuid, but got a %s: %s\", parsed.getClass().getSimpleName(), parsed));\n        }\n    }\n\n    public CQL3Type asCQL3Type()\n    {\n        return CQL3Type.Native.TIMEUUID;\n    }\n\n    @Override\n    public ByteBuffer decomposeUntyped(Object value)\n    {\n        if (value instanceof UUID)\n            return UUIDSerializer.instance.serialize((UUID) value);\n        if (value instanceof TimeUUID)\n            return TimeUUID.Serializer.instance.serialize((TimeUUID) value);\n        return super.decomposeUntyped(value);\n    }","sourceCodeStart":158,"sourceCodeEnd":194,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/db/marshal/AbstractTimeUUIDType.java#L158-L194","documentation":"fromJSONObject expects the JSON-parsed object to be a String containing a timeuuid literal; when it is any other JSON type, the ClassCastException is caught and rethrown as this MarshalException naming the offending type.","triggerScenarios":"Calling AbstractTimeUUIDType.fromJSONObject with a non-String (Integer, Map, List, Boolean, etc.) — e.g. JSON '{\"col\": 12345}' against a timeuuid column.","commonSituations":"JSON-based ingestion APIs where the client sends a number or object for a timeuuid field; schema drift between producer and Cassandra table; generated client code passing parsed JSON values directly.","solutions":["Send the timeuuid as a JSON string literal, not a number or object.","Coerce/validate in application code: if (!(parsed instanceof String)) convert or reject before the call.","Fix the producer's serialization schema so timeuuid fields are strings."],"exampleFix":"// before\nTerm t = type.fromJSONObject(jsonNode.numericValue());\n// after\nTerm t = type.fromJSONObject(jsonNode.textValue()); // e.g. \"d2177dd0-eaa2-11e3-949e-0800200c9a66\"","handlingStrategy":"type-guard","validationCode":"if (!(parsed instanceof String)) throw new IllegalArgumentException(\"timeuuid JSON field must be a string\");","typeGuard":"String asTimeString(Object o) { return (o instanceof String) ? (String) o : null; }","tryCatchPattern":"catch (MarshalException e) { throw new BadRequestException(\"timeuuid must be a JSON string: \" + e.getMessage()); }","preventionTips":["Enforce string typing for UUID fields in your JSON schema (OpenAPI type: string, format: uuid).","Validate incoming JSON payloads against the schema before binding.","Convert numeric timestamps to timeuuids explicitly with UUIDGen.getTimeUUID(bytes, millis) if needed."],"tags":["json","type-mismatch","uuid"],"backgroundTag":"type-mismatch","analyzedSha":"88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1","analyzedAt":"2026-09-10T07:29:22.284Z","contentChangedAt":"2026-09-10T07:29:22.284Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}