--- title: Troubleshooting slug: extensions/troubleshooting docTags: createdAt: 2026-09-22T18:20:22.602Z --- ## No Forter calls are happening at all - `forterEnabled` is `false`. This short-circuits every hook and the storefront snippet template. Check `Merchant Tools > Site Preferences > Site Custom Preferences > Forter - Core Configuration`. - `int_forter_sfra` isn't in the cartridge path, or isn't ordered before `app_storefront_base`. Check `Administration > Sites > Manage Sites > [site] > Settings > Cartridges`. - Metadata wasn't imported. Check whether the `Forter - Core Configuration` group exists at all under `Site Custom Preferences`. If it's missing, re-import `metadata/site_template.zip`. - The device fingerprint snippet isn't rendering. View source on any storefront page and search for `ftr__script`. If `forterEnabled` is `true` and `forterSiteID` is set but the tag is still missing, check for an empty or whitespace-only `forterSiteID`. See [Logging and Snippet Verification](https://docs.forter.com/extensions/logging-and-snippet-verification). - The PSP declined the payment. `postAuthorizationHandling.js` only calls Forter when the payment authorized without error. A processor decline means no post-auth Forter call is ever made. This is expected behavior, not a bug. If none of these explain it, confirm you're checking the right log: Forter writes to the custom `forter` category. See [Logging and Snippet Verification](https://docs.forter.com/extensions/logging-and-snippet-verification). ## 401 Unauthorized on API calls - `forterSecretKey` and `forterSiteID` are both case-sensitive; check for leading or trailing whitespace from a paste. A wrong Site ID also routes calls to the wrong subdomain, and the resulting error can look like a credentials problem. ## Validate call succeeds, but the decision doesn't appear on the order - Check `forterAuthTiming`. Under `PRE_AUTH`, the decision depends on the `session.privacy` to `order.custom` mirror in `postAuthorizationHandling.js`. - Confirm `app.post.auth` is still registered to `./hooks/postAuthorizationHandling` in `hooks.json`. - Check for a shadowed `checkoutHelpers.js`. If a cartridge earlier in the path defines its own `cartridge/scripts/checkout/checkoutHelpers.js`, it can override the Forter one. Enable `forterEnableDebugLogging`, place a test order, and search the log for `Entering Forter pre-auth processing for order {N}`. If that line appears but `order.custom.forterDecision` is still empty, the override is almost certainly shadowing it. - Confirm the custom attributes exist on the Order object: `forterDecision`, `forterOrderLink`, `forterRecommendations`, `forterReasonCode`, `forterRetryNumber`. If metadata import failed, these won't exist and the mirror writes silently fail. ## BM Forter menu is missing - Confirm `bm_forter` is in the Business Manager cartridge path: `Administration > Sites > Manage Sites > Business Manager > Settings > Cartridges`. - Confirm the Forter module is enabled for your role: `Administration > Organization > Roles & Permissions > [Role] > Business Manager Modules > Forter`. - Log out and back in. Business Manager sometimes caches menu definitions. ## `ForterOrderUpdateSFRA` job runs but updates no orders - The job only targets orders with `forterDecision` set to `APPROVED`, `DECLINED`, or `NOT_REVIEWED`. Orders with `FAILED` or `ERROR` decisions are intentionally excluded and never sync. See [Order Status Sync](https://docs.forter.com/extensions/order-status-sync). - The job also only looks back `forterWeeksAmount` weeks from today. An order older than that window won't sync, regardless of its decision. See [Configure Decisions](https://docs.forter.com/extensions/configure-decisions). - Confirm the job is scheduled for the correct site. Jobs are site-scoped. - Confirm the `forter.rest.update` service is reachable via `Administration > Operations > Services`. Its credential URL should be `api.forter-secure.com/v3/platforms/sfcc/status/`, with no `https://` prefix. The service constructs `https://{siteId}.` at runtime. - Confirm a mapper template is deployed for your site. The status endpoint routes through Forter's backend mapper. If the per-site template is missing, every status call returns 500 and the job silently fails every order. Contact your Forter implementation team to confirm it's in place. ## Pre-auth works for registered customers but not guest checkout The cartridge has no branching on customer type. If this happens, it's almost always in the merchant's own code: - A custom `Checkout.js` or `CheckoutServices.js` override that skips logic for guests. - `basket.custom.forterPreAuthOrderNo` missing on the guest basket. It's a standard system custom attribute and works for guest baskets by default; if it's missing, metadata wasn't imported. ## Forter is blocking checkout with no decline reason Only a `void` `processorAction` should ever block checkout. Anything else blocking checkout is a cartridge bug. - Search `custom-forter-*.log` for `Forter pre-auth threw` or `Forter post-auth threw`. Either means a non-`void` exception is bubbling past the fail-open try/catch. - Check `PlaceOrderError.code`. On a real `void` decision, the customer-facing error message derives from this code. If it's empty, the decision object is malformed. ## PII is leaking into production logs - Confirm `forterEnableDebugLogging` isn't `true` in production. Flip it to `false` immediately. - Search the merchant's own cartridge code for `log.info` or `log.debug` calls that reference basket, customer, or payment-instrument data directly. ## Calls are failing intermittently or timing out - Check the `forter.prof` service profile: `Administration > Operations > Services > Service Profiles > forter.prof`. It ships with a 5-second connection timeout and a rate limit of 5 calls per 10 seconds. Raise both if your order volume needs it. - A throttled or timed-out call fails open, so checkout proceeds without a decision instead of showing a visible error. Check `custom-forter-*.log` for retry and fail-open messages. ## General diagnostic approach For anything not on this list: 1. Set `forterEnableDebugLogging` to `true` in sandbox. 2. Place a test order and watch `custom-forter-*.log` line by line. 3. Look for the hook markers `Entering Forter pre-auth processing for order {N}` and `Entering Forter post-auth processing for order {N}`. Whichever is missing narrows the problem to that hook's registration or an early return. 4. Inspect `session.privacy` and `basket.custom` mid-checkout, via a debug log or script debugger. 5. If the behavior still doesn't match what's documented for the cartridge, it's most likely a shadowed override or a metadata gap.