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:
-
Via an exception during the call to an API.
-
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.
- Configuration errors:
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:
- That the certificate is not time-limited or still valid
- 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:
-
Did you specify the right language? - Check your engine or editor configuration and the corresponding
*.conf
file and the selected bundle. -
If you are recognizing text, are guides enabled? - If they are but you are not relying on them, they may negatively impact the recognition.
-
Did you call
WaitForIdle()
before attempting to retrieve the results? - Temporary results may not be as relevant as the final one. - 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.
- Do you send the right content? - If not, you are not likely to get the expected output š!