{"record":{"id":"e5658baf51f61e4e","repo":"quarkusio/quarkus","slug":"could-not-parse-received-event-payload-into-type","errorCode":null,"errorMessage":"Could not parse received event payload into type \" + parameterType.getCanonicalName()","messagePattern":"Could not parse received event payload into type \" \\+ parameterType\\.getCanonicalName\\(\\)","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"extensions/google-cloud-functions/runtime/src/main/java/io/quarkus/gcp/functions/QuarkusBackgroundFunction.java","lineNumber":118,"sourceCode":"\n        // TODO maybe we can check this at static init\n        if ((delegate == null && rawDelegate == null) || (delegate != null && rawDelegate != null)) {\n            throw new IOException(\"We didn't found any BackgroundFunction or RawBackgroundFunction to run \" +\n                    \"(or there is multiple one and none selected inside your application.properties)\");\n        }\n\n        ClassLoader currentCl = Thread.currentThread().getContextClassLoader();\n        try {\n            Thread.currentThread().setContextClassLoader(delegateClassLoader);\n            if (rawDelegate != null) {\n                rawDelegate.accept(event, context);\n            } else {\n                Gson gson = new Gson();\n                try {\n                    Object eventObj = gson.fromJson(event, parameterType);\n                    delegate.accept(eventObj, context);\n                } catch (JsonParseException e) {\n                    throw new RuntimeException(\"Could not parse received event payload into type \"\n                            + parameterType.getCanonicalName(), e);\n                }\n            }\n        } finally {\n            Thread.currentThread().setContextClassLoader(currentCl);\n        }\n    }\n}\n","sourceCodeStart":100,"sourceCodeEnd":127,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/google-cloud-functions/runtime/src/main/java/io/quarkus/gcp/functions/QuarkusBackgroundFunction.java#L100-L127","documentation":"Thrown by QuarkusBackgroundFunction.accept when Gson cannot deserialize the raw event payload string into the parameter type declared by the user's BackgroundFunction implementation. It wraps the underlying JsonParseException so the developer knows both that parsing failed and which target type was attempted.","triggerScenarios":"A background function (e.g. Pub/Sub or Cloud Storage event) delivers a JSON payload whose structure does not match the POJO type passed to delegate.accept(eventObj, context); Gson's fromJson throws JsonParseException.","commonSituations":"Malformed or non-JSON payloads (e.g. Pub/Sub push messages with base64 'data' not decoded before wrapping), POJO field types that Gson cannot coerce (e.g. expecting a nested object when the event has a string), or changed event formats after a GCP service update.","solutions":["Log/inspect the raw event string before parsing and align the POJO field names/types with the actual payload schema","If the payload is a Pub/Sub message, decode the base64 'data' field yourself and parse only that inner JSON","Use JsonElement or Map<String,Object> as the parameter type if the schema is unstable, then map manually","Verify you are not passing a type without a no-arg constructor, which Gson needs for deserialization"],"exampleFix":"// before\npublic void accept(MyPayload payload, Context context) { ... }\n// after\npublic void accept(JsonElement raw, Context context) {\n    MyPayload payload = new Gson().fromJson(raw, MyPayload.class);\n}","handlingStrategy":"try-catch","validationCode":"// validate payload before letting the function parse it\nif (payload == null || payload.isBlank()) {\n    throw new IllegalArgumentException(\"Empty event payload\");\n}\ntry (var reader = new StringReader(payload)) {\n    JsonParser.parseReader(reader); // throws if not valid JSON\n}","typeGuard":"boolean isParsableAs(String json, Class<?> type) {\n    try { new Gson().fromJson(json, type); return true; }\n    catch (JsonParseException e) { return false; }\n}","tryCatchPattern":"try {\n    delegate.accept(eventObj, context);\n} catch (RuntimeException e) {\n    if (e.getCause() instanceof JsonParseException jpe) {\n        LOG.errorf(\"Invalid payload for %s: %s\", type.getSimpleName(), jpe.getMessage());\n        // fall back to JsonElement handling or dead-letter\n    } else throw e;\n}","preventionTips":["Log the raw event payload (or a hash) before parsing in dev","Model your POJO on the documented GCP event schema (Pub/Sub, Storage)","Prefer JsonElement/Map parameter types when the schema may evolve","Unit-test accept() with recorded real event payloads"],"tags":["gcp","json","deserialization","background-function"],"backgroundTag":"json-deserialization-failed","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-12T22:17:10.623Z"}