Is there a chance for more meaningful errors in Stencil being implemented?

[bdobry]

First of all, I want to state that Stencil is great 🚀 This problem just proves how useful and powerful it is :)

Is your feature request related to a problem? Please describe. For longer or more complex documents it is very hard to figure out what is wrong when document doesn't render. When one gets an error message like: 'java.lang.ArithmeticException: Non-terminating decimal expansion; no exact representable decimal result.' or java.lang.IllegalArgumentException: First parameter must be a Collection! to name a few, it doesn't tell right away what is the actual problem. Where did the problem occur, is it a typo, was a Stencil function used incorrectly, is input data incorrect? The only way to figure this out is to do elimination debugging by cutting parts of the document and trying to run everything again with the same data set. It is sometimes quite time-consuming and frustrating.

Describe the solution you'd like In the perfect world scenario, I'd imagine the error to point which Stencil function/fragment caused an issue and/or what data it tried to parse.

Describe alternatives you've considered

Additional context I suspect it's a known problem, but I'm curious if it's being blocked by technical challenges or anything else.

[erdos]

Hello @bdobry, thanks for opening the issue. Sorry for the silence from the last weeks, I had very little allocated time for the side projects. Proper error handling sounds like a feature with big impact. Do you have a specific idea for the implementation?

[erdos]

I think we could introduce new RuntimeException types for the errors to encapsulate the details.

1. Template format exceptions: these would be thrown when preparing a template before rendering. Such as:

   • Syntax errors in template expressions: Mismatching {% ... %} control elements
   • Syntax errors in Stencil expressions (missing closing %}
   • Function errors (missing functions, wrong arities, etc)
   • etc.

2. Exceptions to be thrown during template rendering, including:

   • Wrong values/types passed to functions
   • Division by zero
   • NullPointerExceptions caused by missing data
   • etc.

Both exceptions could include a few characters of text from around the location of the error. Exceptions from (2) could include the whole stencil expression and perhaps event the forbidden values.

We also need to make sure the error details are properly printed by the service.

[bdobry]

@erdos Thanks for a reply! I didn't have a specific idea for the implementation while writing this as I'm not well aware of the technical implications. I like your ideas though, it correlates well with what I had envisioned. But basically anything more than errors from Java would already be a big improvement for our team. I will raise this with my team and see if we can come up with anything more, but this looks solid already.

btw. How complex this would be time-wise? I believe this could be improved somewhat incrementally over time, but do you think we are speaking of weeks or months of development? Anything we could help you with at this point?

[erdos]

hi @bdobry, time-wise I am optimistic because many necessary parts for error handling are already in place. I have started work on it at https://github.com/erdos/stencil/pull/140 based on some earlier ideas and hopefully we can do an initial release maybe end of next week. In the meanwhile, testing the code on the branch locally on some real-life error scenarios would be a great help and speed up the development.

[bdobry]

@erdos Awesome, that sounds very promising! I'll try to get some examples of faulty documents from my team

[bdobry]

@erdos I spoke to my team and they reported back with a few hard to debug errors they came across or errors that appear quite often and take some time to figure out:

1. The most nasty issue we've got probably. We've had a long DOCX template which included {% end %} tag that contained a Non-breaking space between d and % which failed the rendering. It was only returning stencil.exceptions.ParsingException: Unexpected command I believe.

2. Hard to find + quite often: Status: 500, Stencil message: ‘java.lang.NullPointerException’ when a data source key contains some unexpected characters like e.g. dash - or some non-latin characters like ø.

3. java.lang.IllegalArgumentException: Don’t know how to create ISeq from: java.lang.Boolean for example when there is simply a missing & in one of the statements.

4. A few times we had problems with rendering the document at all when there was any issue within a table. The recent one was inserting an opening if tag{% if s1.q1 == "value %} by accident at the end of the last cell in a table, instead of right underneath a table. It took quite some time to identify the issue as it wasn't a direct syntax error but rather a miss-placed tag.

5. A few times we had issues with rendering dates when data source had some non-standard format and it was usually a trial and error until figuring out.

I could prepare some DOCX examples with data sources for the above errors if that helps.

[erdos]

Hey @bdobry thanks for the examples.

~Unfortunately, I could not reproduce the problem mentioned in (1). If it is possible to get a simplified template with this problem, we could investigate it under a separate issue. Until that, I think adding the invalid expression to the error log on parse error could help debug it.~ Being addressed in https://github.com/erdos/stencil/pull/141

We try addressing the rest in a first iteration of #140.

[bdobry]

@erdos Man, that's soo good! You're doing the lord's work 🚀 Is there any other way I could help?

[erdos]

hey @bdobry, I have released version 0.5.0 with the discussed changes. It is still a very early version with a lot of work left for improvements. Please check the new version to see how we can further enhance the error messages.

[erdos]

Closing the ticket for now, please open a new issue for followup and improvements.