Skip to main content

         This documentation site is for previous versions. Visit our new documentation site for current releases.      

Large message exception handling in queue processing

Updated on July 8, 2022

Queue processing automatically handles large messages that exceed the Stream Service default file size threshold. Pega queue processing uses the Stream Service to queue and delegate processing. Automatic handling prevents oversize messages from breaking.

A large message could contain text for an HR email notification, for example, that runs as a background process activity. A message is the data, or input, to a queue processor. It is also referred to as a queued item.

When the Stream Service generates the RecordTooLargeException exception for messages larger than 5MB (the default value), Pega Platform queue processing automatically saves the original message content in a large message storage and replaces the message with an object reference. The message can enter the queue, but as a small message containing only the link to the storage location where the actual message content is kept. When the system later picks up the message for processing, but before the queue processing activity runs, the reference resolves to the original content.

Large message content storage

The system uses the Pega repository service (Data-Repository Pega Platform class) to store the large message content. Queue processing removes the message from the repository after it processes successfully.

If the large message storage is unavailable after making the configured number of maximum attempts, queue processing moves the item to a broken state. It removes the item from the queue and saves it to the delayed messages database. If an item was broken, queue processing purges it after 180 days.

Large message handling configuration

Pega Cloud enables the automatic large message handling feature by default. To make it available for an on-premises or client-managed cloud environment, you must enable the feature and configure a repository. For more information, see Setting up large message handling for on-premises environments.

You disable or enable the large message handling feature, change the name of the large message repository, and change the default base path in the repository by using the following dynamic system settings. For more information, see Editing a dynamic system setting.

Note: If you change any of the queueprocessors dynamic system settings, you do not need restart the system.

Pega-Engine Dynamic system settings for the large exception handling feature

PurposeSetting keyValue
Enable the featurequeueprocessors/largemessagesnapshot/enabledtrue (default)
Disable the featurequeueprocessors/largemessagesnapshot/enabledfalse
Name of the large message repositoryqueueprocessors/largemessagesnapshot/repositorypegacloudfilestorage (default) or a custom string value
Default basepath for the repositoryqueueprocessors/largemessagesnapshot/basepathqueueProcessors/ largeMessageSnapshots (default) or a custom string value
Note: You cannot update the DSS setting for the default repository base path using Dev Studio. For more information, see Configuring dynamic system settings.
Note: The system calculates the default value for the queueprocessors/largemessagesnapshot/enabled dynamic system setting the first time the Stream Service attempts to process an oversize message. If the setting is missing, checks where it was deployed and saves the proper setting value. If the setting already exists, the node skips the initialization.

Have a question? Get answers now.

Visit the Support Center to ask questions, engage in discussions, share ideas, and help others.

Did you find this content helpful?

Want to help us improve this content?

We'd prefer it if you saw us at our best. is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us