Troubleshooting

Start every investigation the same way: set the log level to debug, reproduce the problem and read the lines that start with [Responsly]. See Testing & debugging.

The survey never shows

Find the Survey ID in the log and match what you see with this table.

What the log shows	Cause	Fix
No [Responsly] lines at all	The SDK is not initialized, the log level is not debug, or you are reading the wrong log.	Call initialize at app start with the debug level. Read the native log (Xcode console, Logcat), not the Metro or Dart console. In Expo Go and in the Unity Editor the SDK does not run; see below.
config_unavailable, or an invalid SDK key error	Wrong SDK key, or no network on the first start.	Copy the key again from Share → Mobile app. It starts with rsk_. Restart the app after fixing it.
survey_not_found	The channel is off, the Survey ID is wrong, or the device has an older configuration.	Switch the Mobile app channel on and save. Check the ID. A change takes up to about 10 minutes to reach a device; call reset or reinstall to get it now.
The configuration is downloaded, you call track or screen, and no line mentions the survey	The trigger did not match. Only surveys with a matching trigger are evaluated and logged.	Compare names character by character; they are case-sensitive. Check from occurrence no. and the property conditions. A form with no triggers appears only through showSurvey.
audience_mismatch	The user is not in the audience.	Call identify or setAttributes before the trigger. Check attribute names and value types. Check the identified / not identified rule.
platform_mismatch, app_mismatch, locale_mismatch	The survey is limited to another platform, app ID or language.	Adjust the audience. Debug builds often have a different app ID.
sampled_out	The share of users is below 100% and this install is outside it.	Set 100% while testing.
outside_schedule	The schedule has not started or has ended.	Adjust the dates.
paused or vetoed	Your own code blocked it with pause or the display guard.	Call resume, or check the guard.
disabled	setTrackingEnabled(false) was called at some point. It is saved across restarts.	Call setTrackingEnabled(true).
load_failed	The device is offline or the connection is too slow.	Check the network. The survey needs it at the moment it is shown.
already_completed, frequency_limit, recontact_wait, global_cooldown	It was shown before.	See the next section.

To separate integration problems from targeting problems, call showSurvey with force. If the survey appears, the SDK, the key and the network are fine and the cause is a targeting rule.

The survey shows once and never again

Cause. This is the default. The frequency once shows a survey one time per install, whether the respondent answered or closed it. The log says frequency_limit or already_completed.

Fix.

• For a survey that should come back, change the frequency in the Mobile app tab: until completed, repeatedly (with days between displays) or every time.
• For a button that opens the survey on demand, use every time, or call showSurvey with force.
• While testing, call reset to clear the display history on the device.

If the mode is already until completed or repeatedly, look for recontact_wait (the days between displays have not passed), frequency_limit (the maximum number of displays is reached) or global_cooldown (the team-wide pause between surveys is running).

The survey is in the wrong language

Cause	Fix
The form has no translation for the user’s language, so its default language is used.	Add the translation to the form in Responsly.
An earlier setLocale call is still in effect. The override is saved on the device.	Call setLocale with null (nil in Swift) to return to the device language.
The app has its own language setting that differs from the device language.	Pass the app’s language to setLocale at startup and when it changes.
A locale passed to showSurvey overrides everything else for that call.	Remove it or pass the right tag.
The tag does not match the translation, for example pt-BR when the form’s translation is pt.	Pass the language code the translation uses.

See Language.

The sheet is blank or stays empty

The SDK reveals the container only after the survey has loaded, so an empty container is rare. When it happens:

Cause	Fix
The connection dropped after the survey appeared, and the next page could not load.	Check the network. Listen to surveyError to detect it; call closeSurvey to remove the container.
On Android, the system WebView is outdated or disabled. This is common on emulator images without Google Play.	Update Android System WebView (or Chrome) on the device, or use an emulator image with Google Play.
A VPN, firewall, content blocker or corporate proxy blocks the survey’s address.	Open the form’s link in the device’s browser. If it does not load there either, the network is blocking it.

If nothing appears at all and the log shows load_failed after about 15 seconds, the survey never loaded: the device is offline or the address is blocked.

Expo Go: the native module is missing

Symptom. Every SDK call throws an error saying the Responsly native module cannot be found. Importing the package alone does not fail.

Cause. The SDK contains native code. Expo Go ships a fixed set of native modules and cannot load others.

Fix. Use a development build.

1. Add the config plugin to app.json: "plugins": ["@responsly/react-native-sdk"].
2. Build the native app: npx expo run:ios and npx expo run:android, or an EAS build with a development profile.
3. Open the project in that build instead of Expo Go.

The same applies to a bare React Native app after installing the package: rebuild the native app (and run pod install). Reloading JavaScript is not enough.

Unity: nothing happens in the Editor

Symptom. In Play mode no survey appears. The Console shows a log line for each SDK call.

Cause. By design. In the Editor, and on platforms other than iOS and Android, every call is a no-op that only logs.

Fix. Build and run on an iOS or Android device, simulator or emulator. Use the Editor log lines to check that your calls happen at the right moments.

If a survey appears on the device but the game keeps running behind it, pause in SurveyShown and resume in SurveyCompleted and SurveyDismissed. See Unity installation.

Keyboard problems

Symptom	Cause	Fix
A survey opens while the user is typing, and their keyboard closes.	A trigger fired in the middle of text entry.	Call pause while the user is in a text-entry flow, or veto with a display guard.
With the keyboard open there is little room for the question.	A small sheet, or a phone in landscape.	Use large or full screen for surveys with text answers.
You added keyboard handling around the survey and the layout jumps.	The SDK already moves the container with the keyboard.	Remove it. You do not need KeyboardAvoidingView, resizeToAvoidBottomInset or windowSoftInputMode changes for the survey.

Links open in the browser

Symptom. Tapping a link in a survey leaves the app and opens the system browser.

Cause. By design. The container shows the survey and nothing else. A link that leads to another address, or asks for a new window, is handed to the system browser.

What to do.

• Keep links for things that belong in a browser, such as a privacy policy.
• To send the user somewhere inside your app after a survey, use the surveyCompleted callback and navigate from your own code.
• If the form is set to redirect to another address after completion, that address opens in the browser too, and the survey closes. Remove the redirect on forms you show in the app.

Responses have no user ID or attributes

Cause	Fix
The form has no hidden field with that name.	Add a hidden field named user_id for the user ID, and one per attribute, named exactly like the attribute.
Anonymous responses is on for the form.	Switch it off in the Mobile app tab if you want identified responses.
identify ran after the survey was shown.	Call identify as soon as you know the user. Values are read when the survey is shown.
reset ran before the survey was shown.	reset clears the identity. Call identify again after the next login.

The numbers in the Mobile app tab stay at zero

Cause	Fix
The counts are sent in batches.	Send the app to the background, then reload the tab.
The SDK is switched off with setTrackingEnabled(false).	Nothing is counted while it is off.
The survey never became visible.	Only a survey that actually appeared counts as shown. Check the log.

CocoaPods cannot find ResponslySDK

Cause. The pod is not published to CocoaPods trunk, so pod 'ResponslySDK' alone does not resolve.

Fix. Install it from the package URL you received with your access:

Podfile

pod 'ResponslySDK', :git => '<package URL>', :tag => '1.34.0'

React Native and Flutter projects do not need this line. Their packages bring the iOS SDK with them.

The build fails on the minimum OS version

Cause. The project’s minimums are below the SDK’s: iOS 15 and Android minSdk 23.

Fix. Raise the iOS deployment target to 15.0 (in Xcode and in the Podfile) and minSdk to 23. The installation page of your platform shows where.

A survey appears at a bad moment

Fix. Pick the tool that matches the situation:

• A known stretch of time, such as checkout or onboarding: pause and resume.
• A decision that depends on the current state: a display guard.
• A trigger that fires too early: add a delay in the Mobile app tab, or trigger on a later event.

See Control when surveys appear.

Note

Still stuck? Contact Responsly support with the SDK version, the platform, the Survey ID and the [Responsly] lines from the debug log.