Skip to content
Launch price$9/moLock it in

Troubleshooting

nitpick init stops with exit code 3

There is no valid login. Run npx -y @nitpickhq/cli@latest login, finish it in the browser, then run init again. init never opens the browser or waits for a login itself.

nitpick init stops with exit code 4

init changed nothing, and the builder has to choose or do something first. The message says what:

  • More than one project or app target: it lists them. Run again with --project <path> (the folder or the .xcodeproj) and --target <name>.
  • The account already has apps and init does not guess: it lists them (name, id, platform). Run init --app <id> to link the right one, or init --name "<new name>" to create a new app on purpose.
  • App <id> is not on the account you are signed in with: the app belongs to another account. Run nitpick whoami to see which account is signed in, then nitpick login with the account that owns the app, and run init --app <id> again. Nothing was written or created.
  • nitpick.json links this folder to app <id>, which is not on the account you are signed in with (<e-mail>): the file belongs to an app of another account (exit 4, nothing written or created). Run nitpick login with the account that owns the app, or link one of your own apps with init --replace --app <id>. Do not use --replace --name for this: that creates a second app on the wrong account.
  • nitpick.json already links the folder to another app of your account, or cannot be read: init does not replace it. Fix or remove the file, or run with --replace --app <id> (another of your apps) or --replace --name "<new name>" (a new app) when the builder wants another app.
  • The app is not for iOS, or the iOS deployment target is lower than 17: see below.
  • In human mode, a confirmation is needed and there is no terminal: run with --yes, or with --mode agent.

The deployment target is lower than iOS 17

Nitpick needs iOS 17 or newer; below that the package cannot be installed, not even for general feedback only. init stops (and doctor shows FAIL) and neither changes build settings. Tell the builder; raising the target is their decision. Raise it in Xcode (or platforms: [.iOS(.v17)] in Package.swift), then run init again.

init warns that Xcode is open

init changes project.pbxproj, and Xcode normally reloads it by itself. If Nitpick is missing in Xcode afterwards (no Nitpick under Package Dependencies, or the build cannot find the module), quit Xcode, run nitpick init again and open the project. nitpick doctor shows what is missing.

init did not add the package to an older Xcode project

init edits the project file only in the current format (Xcode 16 and newer). For an older format, or the new JSON format, it changes nothing in the project. The first run still gives status ok (it wrote nitpick.json) with the manual step under Notes; only a repeated run that changes nothing gives steps_open. Add the package in Xcode: File, Add Package Dependencies, the URL and rules of step 1 in Install for SwiftUI, product Nitpick on the app target. Then run nitpick doctor.

XcodeGen or Tuist

If the .xcodeproj comes from project.yml (XcodeGen) or Project.swift (Tuist), init leaves it alone, because the next generate would remove the change. It prints what to add. XcodeGen: the package under packages: and - package: Nitpick with product: Nitpick in the app target's dependencies, then xcodegen generate. Tuist: the package in Tuist/Package.swift and .external(name: "Nitpick") on the app target, then tuist install and tuist generate.

nitpick doctor shows FAIL

Every failing check has a Fix: line. Run it again after the fix; the exit code is 0 when all checks are ok. If the resolve check fails because there is no network, run nitpick doctor --skip-resolve.

The login page does not open

nitpick login prints the address and the code. Open the address yourself. If you run in a remote shell, copy it to a browser on your own machine. The code is valid for 30 minutes, enough to create an account and start the subscription in the browser. After that, run the command again.

nitpick login waits and never gives a token

The token comes only after the subscription runs. Finish the payment in the browser; the page waits a few seconds for the payment provider to confirm and then shows Allow. Press Allow, and the CLI continues by itself. Without a running subscription there is no token, also not through the dashboard.

402 subscription_required

Your account has no running subscription. Creating an app or a token needs one, and changing the status of a report does too. Renew at the address the message shows (<app address>/billing). Reading reports that are not locked keeps working. See Billing and limits.

409 limit_reached

An account has at most 50 apps and 25 tokens that are not revoked. The message names what you can clean up: nitpick tokens list and nitpick tokens revoke <id>, or remove an app you no longer use in the dashboard.

The agent says "invalid token" or 401

Run npx -y @nitpickhq/cli@latest login again, or set NITPICK_TOKEN. A revoked token stops working at once.

Test report does not show up

  • Check that the public key in the app starts with npk_ and belongs to the app you are looking at.
  • Check that the app can reach the API address (apiURL in Swift, apiUrl in React Native). On a real device, localhost is the device, not your Mac.
  • You can send at most 30 reports per minute per app and 10 per minute per IP address. After that you get 429.
  • Screenshots are limited to 1 MB per image. A report with a larger image answers 413 too_large. The components make the image smaller until it fits.
  • The monthly limit of 2,000 reports is reached (429 monthly_limit), or the app is inactive (403 app_inactive). See below.

The tab does not appear

  • SwiftUI: Nitpick.configure(appKey:) must run in the init of the App (.nitpick() on the root view is optional), and the app must require iOS 17 or newer.
  • Expo: NitpickProvider must wrap your navigation, and options.tab must not be false.
  • tabScreens is set. The tab shows only on a screen whose name is in the list; a screen without a name has no tab, and an empty list means no screen. Check the names: with Expo Router the name is the path from usePathname() (/settings/profile, no (group) folders), and /settings/* does not match /settings. Go to a screen in the list, or leave tabScreens out.
  • Both kinds of feedback are off. Run nitpick settings show --app <id>; with General and Point at something both off there is no tab. Turn one on in the dashboard or with nitpick settings set. See Settings.
  • The public key is unknown to the platform (401 invalid_key on the settings request). Check that the key starts with npk_ and is the key of an app on your account. The developer log shows one line about it.
  • No settings have been fetched yet. The tab only shows after a successful request, which happens when the app starts. Without a network it tries again after 30 seconds, up to 3 times, and then when the app comes back to the foreground. On Expo the settings live in memory, so every cold start needs a new request; SwiftUI shows the last good settings from the device. Check apiURL or apiUrl.
  • The subscription does not run any more. After the first 14 days and the 30 days that follow, the tab disappears (active: false, and ingest answers 403 app_inactive). Run nitpick whoami to see the state, and renew at the address it shows. The tab is back within a minute of the next app start after you pay.
  • The monthly limit of 2,000 reports is reached. The tab disappears until the first of the next month (UTC). nitpick whoami shows the usage from 80%.
  • After a change in the settings, wait up to a minute and restart the app, or bring it back after more than an hour in the background.

Your users see "Feedback is not available right now."

That is the sentence the form shows (translated) when the platform answers 403 app_inactive or 429 monthly_limit to a report. It means the subscription has ended long enough that the tab is hidden, or the monthly limit is reached. It says nothing about your users' own account, and they never see why. The draft is dropped, there is no Try again, and the tab goes away until the next valid answer for the settings. Fix the cause (renew, or wait for the first of the month) and the tab returns by itself.

The report says element_match: none

The tap was not in or within 44 points of a marked element. Mark the element with a name, see Screens, elements and masking.

The screenshot misses a map, video or web view

These can come out blank or black on a screenshot that the app makes of itself. The report still has the tap position and the names. Mask them on purpose if they hold anything personal.

The feedback form shows up on the screenshot

It should not: the component removes the tab, the layer and the panel before the screenshot. If you see it, update the package to the newest version.

Expo Go

The component only uses what Expo Go ships. If you added a native module for it, remove it.