quarkusio/quarkus · error · RuntimeException

Could not parse received event payload into type " + paramet

Error message

Could not parse received event payload into type " + parameterType.getCanonicalName()

What it means

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.

Source

Thrown at extensions/google-cloud-functions/runtime/src/main/java/io/quarkus/gcp/functions/QuarkusBackgroundFunction.java:118

        // TODO maybe we can check this at static init
        if ((delegate == null && rawDelegate == null) || (delegate != null && rawDelegate != null)) {
            throw new IOException("We didn't found any BackgroundFunction or RawBackgroundFunction to run " +
                    "(or there is multiple one and none selected inside your application.properties)");
        }

        ClassLoader currentCl = Thread.currentThread().getContextClassLoader();
        try {
            Thread.currentThread().setContextClassLoader(delegateClassLoader);
            if (rawDelegate != null) {
                rawDelegate.accept(event, context);
            } else {
                Gson gson = new Gson();
                try {
                    Object eventObj = gson.fromJson(event, parameterType);
                    delegate.accept(eventObj, context);
                } catch (JsonParseException e) {
                    throw new RuntimeException("Could not parse received event payload into type "
                            + parameterType.getCanonicalName(), e);
                }
            }
        } finally {
            Thread.currentThread().setContextClassLoader(currentCl);
        }
    }
}

View on GitHub (pinned to e1c734241f)

Solutions

1. Log/inspect the raw event string before parsing and align the POJO field names/types with the actual payload schema
2. If the payload is a Pub/Sub message, decode the base64 'data' field yourself and parse only that inner JSON
3. Use JsonElement or Map<String,Object> as the parameter type if the schema is unstable, then map manually
4. Verify you are not passing a type without a no-arg constructor, which Gson needs for deserialization

Example fix

// before
public void accept(MyPayload payload, Context context) { ... }
// after
public void accept(JsonElement raw, Context context) {
    MyPayload payload = new Gson().fromJson(raw, MyPayload.class);
}

// validate payload before letting the function parse it
if (payload == null || payload.isBlank()) {
    throw new IllegalArgumentException("Empty event payload");
}
try (var reader = new StringReader(payload)) {
    JsonParser.parseReader(reader); // throws if not valid JSON
}

boolean isParsableAs(String json, Class<?> type) {
    try { new Gson().fromJson(json, type); return true; }
    catch (JsonParseException e) { return false; }
}

try {
    delegate.accept(eventObj, context);
} catch (RuntimeException e) {
    if (e.getCause() instanceof JsonParseException jpe) {
        LOG.errorf("Invalid payload for %s: %s", type.getSimpleName(), jpe.getMessage());
        // fall back to JsonElement handling or dead-letter
    } else throw e;
}

When it happens

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

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

Related errors

• A background function cannot return a value
• Don't know how to get event data (dataContentType: '%s', jav
• Failed to decode:
• Failed to deserialize extension catalog ${platformJson}
• Failed to deserialize platform descriptor ${json}

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/e5658baf51f61e4e. Report an issue: GitHub.