Troubleshooting Common Error Messages

Jason Piraino

Updated September 30, 2024 18:07

This article contains examples of the most common error messages you may see in the Accelerator GUI or logs, along with information about how to troubleshoot them.

Content Errors

Error(s) rendering template: messages.email.htmlTemplate: The following has evaluated 
to null or missing: ==> Recipient.current_date [in template "htmlTemplate" at line 6, 
column 16] ---- Tip: If the failing expression is known to be legally refer to 
something that's sometimes null or missing, either specify a default value like 
myOptionalVar!myDefault, or use 
<#if myOptionalVar??>when-present<#else>when-missing</#if>. (These only cover the 
last step of the expression; to cover the whole expression, use parenthesis: 
(myOptionalVar.foo)!myDefault, (myOptionalVar.foo)?? ---- ---- FTL stack trace 
("~" means nesting-related): - Failed at: ${Recipient.current_date} [in template 
"htmlTemplate" at line 6, column 14] ----

Similarly, you may see this error message:

This XML query result can't be used as string because for that it had to contain
exactly 1 XML node, but it contains 0 nodes. That is, the constructing XML query has
found no matches.

These are common FreeMarker render errors. The parts in bold are the relevant information. In this example, the template is referencing a recipient field called current_date. This error indicates that there’s no value supplied for that field, which means it’s either empty or missing entirely. In the case of the former, check the recipient data and be sure to add a value for that field. In the case of the latter, make sure that the field is included in the audience query (for Accelerator-based jobs) or the body of the API call (for transactional jobs). In either case, check the referenced line number of the template to see how that field is being used.

If this error message is shown while doing a test send or a recipient preview in Accelerator, check the sample recipient data for the root causes mentioned previously.

Please see below for our FreeMarker documentation pages:

Error(s) rendering template: messages.email.htmlTemplate: Aborting message rendering 
at user request. ---- FTL stack trace ("~" means nesting-related): - Failed at: 
${Gears.doNotSend()} [in template "htmlTemplate" at line 1, column 1] ----

This is a render error created purposely by the ${Gears.doNotSend()} macro. That macro could be in the template HTML or in one of the snippets used by the template. When it’s used, it’s typically with an if/then condition that determines whether or not the job should be sent. These are usually expected and should be ignored, but if this is being triggered in unexpected scenarios, you’ll need to look into the if/then condition and the underlying data it evaluates to determine why the message is not being sent.

This content has personalization errors.  To resolve this issue, please update your 
template, headers, or FreeMarker references.

This is a render error that would be shown while previewing a campaign's recipient data or previewing a template with sample data. It indicates that the provided recipient data is not completely valid for the template or campaign in question. This is usually either an empty value in a field that requires data or a field is referenced by the campaign/template but is missing entirely from the recipient data.

Error occurred writing recipients to batch files

Typically this means there were 0 recipients returned from the audience for a given job, but sometimes it indicates an actual job error. In the latter case, the Accelerator log file will have more details. Look for any mentions of XML formatting errors, database timeouts, or other network/connection errors. If it’s a temporary connection issue, then the campaign can typically be relaunched. If it continues to fail, that indicates there may be a problem with the XML recipient data.

Failed to launch campaign ': VALIDATION_FAILURE :: recipient must be valid 
cross-channel xml; nested exception is PreviewRenderException: : recipient must be 
valid cross-channel xml'

This error message means that either there wasn’t an email address, push address, or SMS address found in the recipient data, or the XML format itself is invalid.

In the case of the former, this can be because it doesn’t exist (no valid addresses were provided) or, more often, the column name of the email address wasn’t explicitly EmailAddress. Using EMAILADDRESS, Email_Address, emailaddress, or any other combination will not work; it must be exactly EmailAddress. The same holds true for push and SMS recipients; the headers for these must be exactly PushAddress and SmsAddress, respectively.

In the case of the latter (invalid XML), it will depend on the type of job. If it’s a bulk/marketing campaign job, invalid XML can potentially be caused by underlying data issues - there could be some recipient data that contains invalid characters, too many characters, or a data format issue. If it’s a transactional job where the full XML is supplied, this usually means there’s a formatting problem with the body of the API call, such as a missing closing tag or other typos.

Error: Error(s) rendering template: messages.push.apns.rawContent: Can't compare values
of these types. Allowed comparisons are between two numbers, two strings, two dates, 
or two booleans. Left hand operand is a sequence+hash (wrapper: f.e.dom.NodeListModel).
Right hand operand is a string (wrapper: f.t.SimpleScalar)

This FreeMarker error indicates that that the template or snippet code is trying to compare two values that have different data types. For example, the code may be attempting to evaluate a text string against a number, which will cause this error. In that scenario, you could potentially use FreeMarker's ?number function to explicitly convert a string of numbers to an actual number data type.

For more information, please see our FreeMarker documentation pages that were linked above. There is also official FreeMarker documentation about the built-in functions that can be used to convert data types: https://freemarker.apache.org/docs/ref_builtins.html.

c.m.a.s.h.l.PreviewFirstRecipientCommand Error Launching campaign [job ID] -
[campaign name] resulted in MessagePreview request errors. Stopping job:

This means that the first recipient in the list ran into a render error. When the first recipient render errors, the job itself fails. Usually, if the first recipient fails to render, that points to a larger issue that often will affect all recipients. As a failsafe to prevent attempting (and likely failing) to render a job with errors, the job itself is marked as failed.

Underneath this error should be another error message with details about the specific reason for the failure.

Document size has exceeded allowed maximum of 5242880 bytes

This means that the amount of supplemental (context) data included in the campaign is over the limit allowed by the MessageGears Cloud. In order to launch the campaign, you'll need to reduce the amount of data returned by the supplemental data query. This can be accomplished by limiting the result set, removing any unnecessary columns/fields, or otherwise modifying the query.

SQL Errors

Error: could not execute statement; SQL [n/a]; nested exception is 
org.hibernate.exception.SQLGrammarException: could not execute statement

This is a generic SQL error that indicates a problem with the SQL syntax. If you’re unsure of which query or specific line of SQL was at fault, open the Accelerator log file and search for this error message. Before the error occurs, there should be information about which query was being launched - most of the time this will be an audience query from a bulk/marketing campaign.

Toward the bottom of the stack trace you will see Caused by. The last Caused by of that trace should provide more specific details about what part of the query was incorrect. It may be as simple as a missing keyword if the error happens every time the query is run. If it’s happening intermittently, it may be an issue with the underlying data, or it could be due to data variables used by the query. For example, an audience query that contains a FreeMarker if condition may be sending different SQL each time it runs.

2023-01-18 11:10:41,612 WARN [mg-task-USER_TASK3] c.m.a.s.AsyncTaskRunner Error 
executing background task Count SQL ContextData: '[ContextDataName]'

com.messagegears.accelerator.modules.datasource.DatasourceReaderInitializationException:
java.sql.SQLException: java.util.concurrent.ExecutionException: 
net.snowflake.client.jdbc.SnowflakeSQLException: SQL compilation error:

syntax error line 21 at position 119 unexpected '',''.

These errors indicate that there is invalid SQL being used in a supplemental data query called [ContextDataName]. The line and position number indicate what part of the query has a syntax problem, so the resolution will be to investigate and modify the supplemental data query.

You may see a similar message for an audience query, and the troubleshooting/resolution would be the same.

If this only happens intermittently when this query is used, then the issue is likely with the data variables or the underlying data itself.

Caused by: com.mysql.jdbc.MysqlDataTruncation: Data truncation: Data too long for 
column 'message' at row 1

The data being inserted by the query exceeds the allowable limit of the column. For example, if the application attempted to insert a 100 character string into a column that only allows 50 characters, this error would be shown.

In this specific example, the message column is referring to a field on the accelerator.notification table (in Accelerator’s MySQL database). This table stores notifications and, in this case, error messages returned by an external audience database. The message field is currently varchar(2000), so if the target database returns an error message longer than 2,000 characters, this error will be thrown by Accelerator. The length of this field will be extended in a future release of Accelerator, so this specific error should become deprecated at that time.

Caused by: net.snowflake.client.jdbc.SnowflakeSQLException: Single-row subquery 
returns more than one row.

This error may be thrown by Snowflake or any other target database. It indicates that the SQL query contains a subquery which is only allowed to find one result, but instead it’s finding more than one.

This is usually something that happens as part of a campaign trigger insert; the SQL statement is meant to insert a row into a target database table, but it’s finding more than one result with a subquery, so the insert statement fails. In this scenario, check the campaign settings to see which pre- and post-campaign triggers are in use. Then, investigate each step of the campaign trigger. Check each subquery in the affected SQL statement by running it individually/separately from the full SQL. If any of them return more than one result, you’ll need to either modify the SQL or modify the underlying data so that the subquery can only find one result.

Failed to launch campaign 'Invalid query; nested exception is 
org.springframework.dao.DataIntegrityViolationException: StatementCallback; SQL 
[insert into {schema.database.table_name} ({field_names})

If you see a message like this, where the query references inserting data into a table, this error will be from a campaign trigger. Follow the steps from the previous example to determine whether it was a pre- or post-campaign trigger, which one it was, and which step of the trigger ran into an error. This is likely to be a SQL syntax error, so you’ll need to review the SQL to make sure the insert script is valid for the destination table.

If it was a pre-campaign trigger that failed, then the job itself likely failed to go out as well. If you do not see a request ID on the job analytics page, that indicates the job did not make it to the MessageGears Cloud, and emails were not delivered to recipients. The job can be relaunched, but the SQL syntax error would need to be resolved first.

If it was a post-campaign trigger, this error means the job was successfully sent to the MessageGears Cloud, but the database insert failed after the job launched. You should see a request ID on the job analytics page in this case, which means that the job itself went out. There is no need to relaunch the campaign, and doing so would result in duplicate emails being delivered. In this scenario, review the SQL for errors and make changes as needed. In order to make up for the missed insert, the best option is to do a one-time manual insert directly in your target database.

Database and Network Errors

Lock wait timeout exceeded; try restarting transaction

This indicates a database table lock - another process locked the table for a long enough time that it caused the job’s process to time out. It could be another campaign running at the same time using an audience that looks at the same tables/datasets, database maintenance locking rows that the audience query is looking at, or something else in the environment. Usually these happen intermittently, and the campaign can be relaunched.

Caused by: java.sql.SQLException: 
com.mysql.jdbc.exceptions.jdbc4.CommunicationsException: Communications link failure

The last packet sent successfully to the server was 0 milliseconds ago. The driver 
has not received any packets from the server.

These errors indicate that the database is not accessible from the Accelerator server. Typically this means there’s a network issue such as a firewall block, a lock in the database, the database server is down, or it’s a temporary connectivity problem in the environment.

It could also indicate that a query is taking longer to complete than the allowable timeout. If this is affecting the Accelerator MySQL database, the timeout settings (in milliseconds) are in the JDBC string of the /opt/messagegears/conf/database.properties file on the Accelerator server. If it’s a different database, the timeout settings would be controlled by that database’s timeout settings.

If this is a new database connection, try making the connection directly from the server itself on the command line. If it fails, that confirms that the issue is not with Accelerator. If it’s successful, try updating or recreating the database connection in Accelerator. Depending on your database server type, there may be additional JDBC parameters you can add in the database connection setup screen.

Caused by: javax.crypto.IllegalBlockSizeException: Input length must be multiple of 8 
when decrypting with padded cipher

This means that the password in the database.properties file on the server is unencrypted, but the parameter encrypted=true is set. Delete the encrypted=true line in database.properties, and restart Accelerator/Tomcat. The file is located in /opt/messagegears/conf.

Caused by: org.hibernate.exception.GenericJDBCException: Unable to acquire JDBC 
Connection

Caused by: java.sql.SQLException: An attempt by a client to checkout a Connection has 
timed out.

Caused by: com.mchange.v2.resourcepool.TimeoutException: A client timed out while 
waiting to acquire a resource from 
com.mchange.v2.resourcepool.BasicResourcePool@406836f3 -- timeout at awaitAvailable()

If you see any of these 3 Caused by messages, it means that Accelerator is unable to get a JDBC connection to the database. This will typically not be referring to the Accelerator MySQL DB, but another JDBC connection you have set up in your ‘Accelerator -> Admin -> Database Connections’ section. Check that the DB is online and accepting connections, and follow the troubleshooting steps mentioned for other DB connection errors (test from the command line if possible, check credentials, check network connectivity).

WARN [localhost-startStop-1] o.f.c.i.d.JdbcTemplate [MDC:   ] DB: Integer display 
width is deprecated and will be removed in a future release. (SQL State: HY000 - 
Error Code: 1681)

WARN [localhost-startStop-1] o.f.c.i.d.JdbcTemplate [MDC:   ] DB: 'utf8' is currently 
an alias for the character set UTF8MB3, but will be an alias for UTF8MB4 in a future 
release. Please consider using UTF8MB4 in order to be unambiguous. (SQL State: HY000 
- Error Code: 3719)

These errors indicate that MySQL 8.0 is being used, which is not supported prior to Accelerator 23.3.2. Accelerator versions prior to 23.3.2 require MySQL 5.7.

optimistic locking failed; nested exception is org.hibernate.StaleObjectStateException:
Row was updated or deleted by another transaction (or unsaved-value mapping was 
incorrect) : [com.messagegears.accelerator.bo.MarketingCampaign#21166]

This error can happen if a count is run on a campaign while that campaign is already extracting recipients for a job launch. To avoid the error, wait until the campaign's job has started delivering to recipients before running another count.

Other Errors and Issues

Failed to convert from type [com.messagegears.accelerator.async.AsyncTask] to type 
[com.messagegears.accelerator.ui.support.AsyncTaskDto] for value 
'com.messagegears.accelerator.async.AsyncTask@db937d5e'; nested exception is 
com.messagegears.accelerator.service.AsyncTaskNestedRuntimeException: the content of 
elements must consist of well-formed character data or markup.

You may see this error when using an uploaded CSV or XML file as an audience. Most often, the root cause is the header row: similar to SQL audiences, the header row for email addresses must be exactly EmailAddress.
This error can also indicate that one or more email addresses in the list is invalid. Double check the list for any malformed addresses.

This error can also be caused by Excel or another application saving the file with incorrect encoding. The available encoding options, as shown in the dropdown menu on that screen, are UTF-8 and UTF-16 (UTF-8 is more common). Excel or other applications may incorrectly save the file as UTF-8 with BOM encoding, even when specifically deselecting that option. The workaround is typically to copy the data out of Excel and into Notepad++ (or an equivalent text editor), and then to save the file as regular UTF-8 encoding.

????????????????????????????????????????????????????????????????????????????

If you're using non-standard characters in a template (such as emojis or other languages) and see question marks or other invalid/garbled characters in place of them, this indicates that the MySQL database encoding is set to utf8 instead of utf8mb4. Please refer to our installation instructions for information on how to set utf8mb4 encoding in a local MySQL database. If you're using RDS, please see our recommended RDS configurations page for details.

Error creating filename.csv, Error message: Access Denied (Service: Amazon S3;
Status Code: 403; Error Code: AccessDenied

This error message could happen on an external campaign launch. If received, it means that the credentials for the external campaign are invalid or the external destination is configured to block incoming connections from the MessageGears Cloud. When this happens, the external job will be marked as failed, and the CSV would not be able to make it to the destination.

User-specific or Post-upgrade GUI Issues

If you're running into an issue that others are not experiencing, the culprit is almost always the browser cache and/or site data. Cache problems may also happen after an Accelerator upgrade if you're experiencing slow page loads or display issues. The quickest and easiest way to clear the site data for Accelerator is to do the following:

Log out of Accelerator.
- Note: if you're logged in via SSO and cannot manually log out, you can perform the next two steps while still logged into Accelerator.
Make sure Google Chrome is updated to the latest version.
While still on the Accelerator login page, clear cache for the Accelerator site. For Chrome, open the Chrome Developer Tools (CMD+Option+I on a Mac, or CTRL+Shift+I or F12 on Windows, Linux, and Chromebooks). Right click on the Reload icon in the browser and select "Empty Cache and Hard Reload."
Log back into Accelerator.