Error management

This page explains how to manage errors with iink SDK, as well as common pitfalls

Getting error notifications

There are two ways iink SDK may return an error:

  1. Via an exception during the call to an API.

  2. Via IEditorListener.onError() when the error occurs in a background thread.

Exceptions

Possible exceptions for each API call are described in detail in the corresponding API headers.

Editor-level errors

It is highly recommended that you implement IEditorListener.onError() as part of your integration. This callback provides detailed messages to explain what happened.

In addition, this method comes with an error code argument that will help you customize or internationalize messages to guide your customers in their use of iink technology.

The following table lists the main errors and their possible causes.

Error code Message Possible cause/solution
GENERIC ā€œerror: no such configurationā€ The configuration file could not be found. Check that the folder containing the *.conf file is referenced by the configuration-manager.search-path key of your engine or editor configuration.
GENERIC ā€œerror: no such configuration bundleā€ The configuration bundle could not be found. Check that a bundle with the provided name exists in the *.conf file specified by your engine or editor configuration.
GENERIC ā€œerror: invalid configuration typeā€
ā€œerror: failed to expand environment variables in placeholders ${}ā€,
ā€œerror: invalid command ā€œ
…
There was an error when parsing the *.conf files. Many variants of this message exist, and each of them should be self-explanatory.
  • Ink errors, when ink cannot be added to a Text Document:
Error code Message Possible cause/solution
INK_REJECTED_TOO_SMALL ā€œink rejected: stroke is too small (write larger)ā€ The stroke you sent to the part is too small. It may originate from the use of a wrong dpi value to configure the renderer.
INK_REJECTED_TOO_BIG ā€œink rejected: stroke is too large (write smaller)ā€ The stroke you sent is too large vertically: a Text Document part assumes that ink is written on, and not across, the guides.
INK_REJECTED_ABOVE_FIRST_LINE ā€œink rejected: stroke is above first lineā€ Ink was written within the top margin.
INK_REJECTED_BEFORE_FIRST_COLUMN ā€œink rejected: stroke is too far left of the first columnā€ Ink was written too far left.
INK_REJECTED_SMALL_TYPESET ā€œink rejected: cannot write on DIGITAL PUBLISH paragraphs (convert to DIGITAL EDIT)ā€ Text blocks in DIGITAL_PUBLISH conversion state can only receive edit/decoration gestures but no input. You have to convert them to DIGITAL_EDIT to add extra content.
INK_REJECTED_OUT_OF_PAGE ā€œink rejected: stroke is out of document boundsā€ Ink was written outside of the document bounds. Note that each time content is added, iink SDK will allocate extra vertical space at the end of the page corresponding to the height of the provided view size.
INK_REJECTED_TOO_LONG ā€œink rejected: stroke is too longā€ The length of the stroke (i.e. its number of points) exceeds what the engine can process.
  • Gesture errors, when an ink gesture has been detected into a Text Document, but cannot be applied:
Error code Message Possible cause/solution
GESTURE_NOTIFICATION_NO_WORDS_TO_JOIN ā€œgesture: no words to joinā€ A join words gesture has been detected but no words to join have been found.
GESTURE_NOTIFICATION_MESSAGE_CANNOT_MOVE_ABOVE_FIRSTLINE ā€œgesture: there is no line above to joinā€ A join line gesture has been detected on the first line so no there is no line above to join.
GESTURE_NOTIFICATION_MESSAGE_UNABLE_TO_APPLY ā€œgesture: gesture cannot be appliedā€ A gesture has been detected but an unexpected error has been encountered
  • Other errors :
Error Message Possible cause/solution
Import Error ā€œcould not import JIIX: transform contains a skew or a rotation componentā€ You imported a JIIX with a transform containing a skew or a rotation component but only scale and translate are now allowed.
Too many strokes to process ā€œLIMIT_EXCEEDEDā€ You sent more strokes to the recognition engine than what it can concurrently process.
Unexpected error ā€œINVALID_STATEā€ or ā€œINTERNAL_ERRORā€ The recognition engine encountered an unexpected error.

Engine-level error

Error Message Possible causes/solutions
Package cannot be opened ā€œerror: package is already openedā€ Before closing a contentPackage, you shall ensure the editor is in idle state, and that no object referencing this contentPackage remains.

Certificate errors

It usually takes the form of an INVALID_CERTIFICATE message printed to the console.

If this occurs, please check:

  1. That the certificate is not time-limited or still valid
  2. If you retrieved the certificate from the Developer Portal, check that it was generated for the bundle ID of your application.

No recognition

If recognition is not working, you may usually get the root cause by looking at errors raised by the editor:

The following causes are the most likely to be involved:

  • The configuration was not found - Ensure that the *.conf file you reference is part of the paths provided to the engine/editor and that the name of the bundle is correct.
  • Recognition assets could not be found - Ensure that the recognition assets are properly deployed alongside your application and properly referenced by the *.conf file.

Recognition quality is poor

Here is a small checklist to consider in this case:

  1. Did you specify the right language? - Check your engine or editor configuration and the corresponding *.conf file and the selected bundle.
  2. If you are recognizing text, are guides enabled? - If they are but you are not relying on them, they may negatively impact the recognition.

  3. Did you call waitForIdle() before attempting to retrieve the results? - Temporary results may not be as relevant as the final one.

  4. Did you provide proper dpi value when instantiating the renderer? - This is fundamental to provide the engine with a sense of ā€œscaleā€, which may let it for instance differentiate a circle, a letter ā€œoā€ or a dot, if context is lacking.
  5. Do you send the right content? - If not, you are not likely to get the expected output šŸ˜‰!

We use cookies to ensure that we give you the best experience on our website • Read the privacy policy