Cryptic error messages com.stripe-terminal:InternalErrorCode=5100

[majjinator]

Summary

Most error messages that arise from the SDK are comprehensible enough to deduce what the root cause of the issue is. However, there are some vague error messages that give no indication as to the root cause of the issue. For example, when running on an iPhone XS device, the error below will intermittently arise when attempting to connect to a card reader after the discovery process has concluded successfully:

Error Domain=com.stripe-terminal Code=5000 "An unexpected SDK error occurred." UserInfo={com.stripe-terminal:InternalErrorCode=5100, NSLocalizedDescription=An unexpected SDK error occurred., com.stripe-terminal:Message=An unexpected SDK error occurred.}

I'm guessing the error code 5100 means something, but it is not in the list of error codes documented at https://stripe.dev/stripe-terminal-ios/docs/Enums/SCPError.html

It would be great to have these types of error messages replaced with actionable error messages, or documented in the SCPError page above. In the meantime, what is the recommended way to figure out what InternalErrorCode=5100 means?

Code to reproduce

   let connectionConfig = BluetoothConnectionConfiguration(locationId: presentLocationId, autoReconnectOnUnexpectedDisconnect: autoReconnectOnUnexpectedDisconnect, autoReconnectionDelegate: ReconnectionDelegateAnnouncer.shared)
   Terminal.shared.connectBluetoothReader(reader, delegate: BluetoothReaderDelegateAnnouncer.shared, connectionConfig: connectionConfig, completion: connectCompletion)

PS: The above code is from the Example app included with the SDK

iOS version

16.4.1

Installation method

pod install

SDK version

2.20.2

Other information

Error occurs intermittently. I have not been able to identify the precise conditions to replicate the error. Happens with Reader M2 as well as Chipper 2X.

[bric-stripe]

In the meantime, what is the recommended way to figure out what InternalErrorCode=5100 means

unfortunately there isn't a good recommendation here as the goal is that the SDK ideally never has to return this. It's possible if you log all the events from the log listener it may hint at what the problem is but it would be an internal SDK issue so there may not be anything actionable for you to do with the info other than including it in an issue. So the recommendation would be to do what you did and let us know that you're hitting these and we can take a look¹. I'll review the 5100's hit during connect but do you have any other details of instances you've seen? Are these new in 2.20.2? If so, what was the previous SDK version you were using? Having a reader serial number of rough time would be great too (just want to make sure I dig in to the right thing).

Footnotes

1. we also periodically review the internal error codes that are being hit to try to debug and fix them but filing an issue with any details like you have helps us prioritize them too. ↩

[majjinator]

I'll configure a log listener and see if it emits any useful information that I can relay. We have tested all the SDK versions from 2.7.0 onwards and encountered the issue. Once I get the log listener output, I'll relay the details including terminal id and execution times.

[bric-stripe]

from looking at a few samples I've found a possible race condition in what I believe is a discover > connect > connect fails¹ > cancel discover > retry loop. I'm still trying to reproduce and narrow some things down though, so if you get any more logs or data please do pass it along.

Footnotes

1. in the samples I'm seeing the common error is SCPErrorBluetoothConnectionFailedBatteryCriticallyLow but I suspect any connect failure could expose the race condition ↩

[majjinator]

Here some additional logs, after setting logLevel to verbose. Both of them appear to point to an unexpected nil value for reader.adapter

Reader M2

[StripeTerminal] s scope=SCPTerminal event=connectReader_start logpoint_level=info app_id=xyz command=connectReader device_type=Stripe_M2 last_request_id=req_L53cjB8T3ethQf multiple_readers_connected=false sdk_version=2.20.2 serial_number=STRM26138005117 time=1685468350591

[StripeTerminal] l scope=SCPTerminal event=unexpected_state logpoint_level=warning app_id=xyz last_request_id=req_L53cjB8T3ethQf sdk_version=2.20.2 time=1685468350603 unexpected_nil=reader.adapter

Chipper 2X

[StripeTerminal] s scope=SCPTerminal event=connectReader_start logpoint_level=info app_id=xyz command=connectReader device_type=Chipper_2X last_request_id=req_vtPQtrkiw8HcXR multiple_readers_connected=false sdk_version=2.20.2 serial_number=CHB204909012155 time=1685468709496

[StripeTerminal] l scope=SCPTerminal event=unexpected_state logpoint_level=warning app_id=xyz last_request_id=req_vtPQtrkiw8HcXR sdk_version=2.20.2 time=1685468709510 unexpected_nil=reader.adapter