Troubleshooting and monitoring Functions

This page helps you diagnose common function errors and monitor function performance in production. The troubleshooting section is organized by symptom — start with what you observe, then follow the cause and fix.

Monitoring

CloudWatch metrics

MediaTailor publishes metrics for function execution to Amazon CloudWatch. No opt-in is required.

Hook-level metrics — one data point per lifecycle hook execution:

Function-level metrics — one data point per individual function execution:

For more details on setting up alarms and working with these metrics, see Monitoring AWS Elemental MediaTailor with Amazon CloudWatch metrics.

Log events

MediaTailor emits log events for function execution. Error events are emitted by default. Completed and summary events are opt-in.

To enable opt-in log events, see Monitoring AWS Elemental MediaTailor with Amazon CloudWatch metrics.

Use the eventId field to correlate hook-level and function-level events for the same execution.

The following Amazon CloudWatch Logs Insights query filters function error events by eventId to trace a single execution:

fields @timestamp, eventType, functionId, errorType, cause
| filter eventId = "5dc6f040-0f72-4e8c-a64e-25eeef62708c"
| sort @timestamp asc

Troubleshooting

When a function fails, MediaTailor logs an errorType field in the error event. Use this field to identify the class of failure:

The entries are organized by symptom and reference these error types where applicable.

Expression returns null unexpectedly

Symptom: An output value you expected to be populated is null or missing from player parameters.

Possible causes:

RESOURCE_LIMIT_ERROR: Stack overflow

Symptom: The function fails with errorType: "RESOURCE_LIMIT_ERROR" and cause: "Stack overflow error".

Cause: The expression exceeded the maximum stack depth of 100 levels. This typically happens with deeply nested conditional (if/then/else) expressions or complex variable assignments.

This means the expression has too many levels of nesting for MediaTailor to process.

Fix: Simplify the expression. Break complex logic into multiple output entries or multiple steps in a sequential executor.

RESOURCE_LIMIT_ERROR: CPU timeout

Symptom: The function fails with errorType: "RESOURCE_LIMIT_ERROR" and cause: "Expression evaluation timeout: Check for infinite loop".

Cause: The expression exceeded the 100 ms CPU time limit. This can happen with expressions that perform expensive computations over large data structures.

Fix: Reduce the complexity of the expression. If you are processing large arrays, consider moving that logic to an external service and calling it with an HTTP_REQUEST function.

RESTRICTION_ERROR: Function not allowed

Symptom: The function fails with errorType: "RESTRICTION_ERROR" and cause: "Function '<name>' is not allowed".

Cause: The expression calls a JSONata function that is not in the allowed list of 44 functions. Common examples include $eval, $assert, $error, $sift.

Fix: Check the cause field for the blocked function name. Replace it with an allowed alternative. See JSONata expression reference for the full list of 44 allowed functions.

Commonly used allowed functions include $string, $number, $substring, $contains, and $encodeUrlComponent.

RESTRICTION_ERROR: Expression too long

Symptom: The function fails to create or update with cause: "Expression length <actual> exceeds limit <limit>".

Cause: A single expression exceeds 1,000 characters.

Fix: Break the expression into smaller parts. Use multiple output entries, or split the logic across multiple steps in a sequential executor. Use variable binding (:=) to avoid repeating long subexpressions.

HTTP error: Status code is null

Symptom: In an HTTP_REQUEST function's output, response.statusCode is null.

Cause: The external API was unreachable, the connection timed out, or a network error occurred. When this happens, MediaTailor sets response.statusCode to null, response.body to null, and response.text to "Internal Error".

Fix: Always check response.statusCode before accessing response data:

{%response.statusCode = 200 ? response.body.value : 'default'%}

This expression checks whether the HTTP call returned a 200 status code. If it did, it uses the response value. Otherwise, it falls back to a default value.

If this happens frequently, check whether the external API is healthy. Consider increasing RequestTimeoutMilliseconds if the API is slow, or decreasing it if you want to fail fast.

HTTP error: Response body is null

Symptom: response.statusCode is 200 but response.body is null.

Cause: The response body is either not valid JSON or exceeds 20,000 characters. MediaTailor only parses JSON responses up to 20,000 characters into response.body.

Fix: Use response.text as a fallback. The response.text field contains the raw response body truncated to 20,000 characters:

{%response.statusCode = 200 ? ($exists(response.body.id) ? response.body.id : $substring(response.text, 0, 100)) : 'error'%}

If the data you need is beyond the 20,000-character limit, consider asking the external API to return a smaller response (for example, by requesting specific fields).

HTTP error: URL validation failure

Symptom: The function fails at runtime with a message about the URL being malformed, using an invalid scheme, or exceeding the maximum length.

Possible causes:

VALIDATION_ERROR

Symptom: The function fails with errorType: "VALIDATION_ERROR". This error can occur at authoring time (when you create or update the function) or at execution time (when the function runs during a session).

Possible causes:

Check the cause field in the error log event — it identifies which field or expression failed validation.

INTERNAL_ERROR

Symptom: The function fails with errorType: "INTERNAL_ERROR".

Cause: An infrastructure failure occurred that is unrelated to your function configuration.

Fix: Retry the request. If the error persists, contact AWS Support.

Ad list change has no effect

Symptom: Your function runs without errors at POST_ADS_RESPONSE or PRE_MANIFEST_INSERTION, but the ads in the stream are unchanged. A filter, reorder, or modification appears to be ignored.

Possible causes:

To confirm what your function actually returned, opt in to the FUNCTION_COMPLETED event types for the hook and inspect the function output in the ADS interaction log.

Injected ad doesn't appear in the manifest

Symptom: Your PRE_MANIFEST_INSERTION function returns an injected ad and completes successfully, but the ad is not in the rendered manifest.

Injection checks run after your function returns, so the function's log events report success even when an injection is dropped. Check the following causes in order: