Textguard docs
v1.0.0
Get help
● Ship

Troubleshooting
common problems and fixes.

Real cases from the code and the build, with what to check.

rulesiOS filterpurchasesserverbuild

01The iOS filter does nothing

The extension is only called for texts from senders who are not in the user's contacts, and only after the user switches it on: Settings, Messages, Unknown & Spam, Text Message Filter, Textguard. It also needs a matching App Group in both targets (Rename); otherwise it falls back to the rules bundled in the extension. Test with a real text from an unknown number on a real iPhone.

02New rules reach the app but not the iOS filter

The app hands the rule pack to the filter through the App Group when it runs. After you change rules in the console, open the app once (Message filter screen, Update the filter now).

03Android does not check incoming texts by itself

By design: see Android and iOS limits. The user selects text and chooses Check with Textguard, shares it to the app, or pastes it. If you renamed the package, the channel name in brand.dart must match MainActivity.kt, and the Kotlin folder and package line must match the new application id (Rename).

04A real text was flagged, or a scam was missed

The 46 starter rules are a starting point. Open the result, read which rules matched, lower the weight or disable a rule in the console (Rule packs), and add rules for the scams you see. Run the pack on your own real messages before you promise anything in a listing.

05The console refuses my pattern

Patterns are checked for safety when you save them: at most 160 characters, no back-references, no look-ahead or look-behind, no nested open-ended repeats such as (a+)+, no alternation under * or +. Rewrite the pattern as several simpler rules or use a keyword.

06The paywall says purchases are not set up

No product id is set for this platform. Fill the ids in brand.dart or the console (Where to put the ids). Ids must match App Store Connect and Play Console exactly.

07Products are set but the store returns nothing

iOS: the Paid Apps agreement and tax forms must be complete and the product ready to submit. Android: the app must be installed from a Play test track (not a sideloaded APK) by a licence tester, and the product and base plan must be active. Wait some hours after creating products.

08Purchase verification answers 501

501 verification_off means verification is not switched on in the console, so the app trusts the on-device result. Turn it on under Purchases and fill in the credentials.

09Google Play verification fails with a permission error

The service account must be invited in Play Console with View app information and View financial data, and the Android Publisher API must be enabled in the Google Cloud project. New permissions can take some time to apply.

10App Store lookup fails

Check the bundle id, Key ID, Issuer ID, and that the .p8 text was pasted whole including its BEGIN and END lines. The server tries Production, then Sandbox.

11I cannot find the console setup code

It is printed in the server log at start when ADMIN_SETUP_TOKEN is empty. In Docker run docker logs. Or set ADMIN_SETUP_TOKEN in .env and restart.

12npm ci fails or better-sqlite3 will not load

Use Node 22.12 or newer (node -v). better-sqlite3 is a native module: if no prebuilt file exists for your system, you need build tools (Python 3, make, a C++ compiler). Delete node_modules and run npm ci again after changing Node versions.

13429 errors, or everyone shares one address

/v1 routes allow 60 requests a minute per address. Behind a proxy set TRUST_PROXY_HOPS=1, otherwise all users look like the proxy's address.

14A console change does not appear in the app

The config is cached for 5 minutes and by ETag. Wait, then reopen the app. Check the app was built with API_BASE_URL and that the address is https and reachable from the phone.

15Play rejects the upload or says the app is debug-signed

As shipped, release builds use the debug key. Add your own signing config (Release).

16Xcode says signing failed or the bundle id is not available

The project ships with no team set. Choose your own team and a bundle id you own (Rename).

17iOS build fails on a pod deployment target

The Podfile platform is 16.0 because current Xcode rejects older pod targets. Keep it at 16.0 or higher, then run pod install again.