Critical: runSyntheticHandler returns 200 in case of error thrown

[lucabrunox]

Hi,
I've encountered a problem that seems very critical: runSyntheticHandler returns 200 even if an error is thrown.

Impact

This is a critical bug, runSyntheticHandler is advertised in the official documentation and people might be missing on alerts created on monitoring.googleapis.com/uptime_check/check_passed which is always 100% even if the function fails.

Reproduce

To reproduce:

const functions = require("@google-cloud/functions-framework");
const {runSyntheticHandler} = require("@google-cloud/synthetics-sdk-api");

functions.http('test', runSyntheticHandler(async ({ logger, executionId }) => {
   logger.info("foo");
   throw new Error("some error");
}))

The result of calling the function is:

$ curl -i http://localhost:8080/
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 879
Date: Mon, 09 Mar 2026 13:34:59 GMT
Connection: keep-alive
Keep-Alive: timeout=5

{"synthetic_generic_result_v1":{"ok":false,"generic_error":{"error_type":"Error","error_message":"asd","function_name":"","file_path":"/home/somewhere/functions/myfunction/index.js","line":8,"stack_trace":"Error: asd\n    at /home/somewhere/functions/myfunction/index.js:8:10\n    at runSynthetic (/home/somewhere/node_modules/@google-cloud/synthetics-sdk-api/build/src/handlers.js:34:15)\n    at process.processTicksAndRejections (node:internal/process/task_queues:95:5)\n    at async /home/somewhere/node_modules/@google-cloud/synthetics-sdk-api/build/src/handlers.js:83:18"}},"runtime_metadata":{"@google-cloud/synthetics-sdk-api":"0.5.1"},"start_time":"2026-03-09T13:34:59.808Z","end_time":"2026-03-09T13:34:59.810Z"}

Where is the bug

The bug is that this piece of the code that doesn't set res.status(500):

synthetics-sdk-nodejs/packages/synthetics-sdk-api/src/handlers.ts

Line 50 in 71dbe89

} catch (err: unknown) {

Expected

I would expect an error 500, otherwise the check_passed metric is always successful.

[Resteklicken]

Where in the documentation for uptime checks does it tell you to use runSyntheticHandler? Take this code snippet for example.
The synthetic monitor sets the "ok" field in "synthetic_generic_result_v1" to false to indicate a failed monitoring operation, separate from the HTTP status code.

[lucabrunox]

@Resteklicken here https://docs.cloud.google.com/monitoring/synthetic-monitors/samples

It doesn't matter what the custom field does, what matters is that the google check_passed metric uses the http status code.

[Resteklicken]

From my own observation I have to disagree. My check_passed metric correctly went to false on error, despite a 200 response code.

In the documentation of the uptime_check metrics you can find seperate metrics for passed, http_status, etc., but no info on the internals of the metric. What makes you think that it derives from the HTTP status code? Additionally, the check_passed metric has no label for http_status. Seems weird if that's what it uses to determine its value, right?

The details shown on the synthetic monitoring page stem from a log entry from projects/<PROJECT>/logs/monitoring.googleapis.com%2Fuptime_checks. That entry contains a lot of error information from the run but it does not contain the response code. I find it way more likely that the metric is based on this log.

[lucabrunox]

The reason I say that is because once I tweaked the code to return 500 then check_passed metric started working as expected. I don't have a sample log anymore, I would have to revert the workaround etc.

function runSyntheticHandlerWorkaround(syntheticCode) {
    let handlerFunction = runSyntheticHandler(syntheticCode)
    return async function (req, res) {
        let origSend = res.send;
        let called = false;
        res.send = function (body) {
            // express calls res.send recursively after serializing to json
            if (!called) {
                called = true;
                if (!body || !body.synthetic_generic_result_v1 || body.synthetic_generic_result_v1.ok === false) {
                    res.status(500)
                }
            }
            return origSend.apply(res, arguments);
        }
        await handlerFunction(req, res)
    }
}