rConfig Vector Prism – Troubleshooting

rConfig Vector Prism Troubleshooting: Common Issues and Resolutions

This page collects the most common problems Prism operators and customer users see, organized by symptom. For each issue, the page lists the typical cause, where to look in the running Prism instance, and how to resolve it.

Note

Detailed runbooks (with version-specific commands and database queries) live inside your Prism instance at /admin/docs/troubleshooting. This page is the public-facing symptom catalogue.

Sign-In and Authentication

Customer can’t accept their invitation

Symptom: customer reports the signup link doesn’t work or shows an “invitation expired” message.

Likely cause: invitation links expire after 24 hours; the customer waited too long, or the email landed in a quarantine and was opened late.

Resolution: open /admin/users, find the invited user, and click Resend invitation. A fresh link is queued. If your relay is slow or the recipient’s inbox is heavily filtered, also confirm the recipient address is correct and not in a typo’d state.

Customer can sign in but gets stuck on the 2FA enrollment page

Symptom: user reports they sign in, see a QR code, but every code they enter is rejected.

Likely cause: clock skew between the user’s phone and the Prism server. TOTP allows a 30-second window, but if either clock is off by more than that, codes will be rejected.

Resolution: ask the user to enable automatic time sync on their phone (it’s almost always disabled time on the user side, not the server). On the Prism server, confirm NTP is running (systemctl status systemd-timesyncd or equivalent). The sidebar clock widget shows Prism’s wall clock — compare it to wall-clock-on-the-wall.

User has lost their authenticator and used all recovery codes

Symptom: user can’t sign in; their authenticator is gone; recovery codes have all been used or were never saved.

Resolution: as an admin, open /admin/users, find the user, and click Reset 2FA. A notification email is queued and the user’s stored 2FA secret is cleared. On their next sign-in attempt, they’re sent through the enrollment flow again. The action is logged in the audit log (user.two_factor_reset).

Admin has lost access (no other admin to reset 2FA)

Symptom: the only admin can’t sign in and there’s no second admin to bail them out.

Resolution: this requires database-level intervention to clear the 2FA columns on the user row. The exact SQL is in the in-app docs at /admin/docs/troubleshooting/admin-lockout — you’ll need shell access to the Prism host. Prevention: always run two admins in production (see Best Practices).

”Account locked” message after several failed sign-ins

Symptom: user sees an account lockout page after multiple bad password attempts.

Cause: Prism (via Jetstream) locks the account after consecutive failed sign-ins to slow down credential-stuffing attacks. A notification email goes to the user.

Resolution: wait the cool-down period (printed on the lockout page), or as an admin you can manually unlock from /admin/users. If lockouts are happening regularly to legitimate users, your password policy may be too aggressive or your reverse proxy may be confusing real attempts with retries.

Empty or Wrong Device List

Customer sees “No devices yet” on their portal

Most likely cause: the customer’s team has no tags mapped, or the mapped tag has no devices in rConfig.

Resolution:

1. Open /admin/tag-mappings and click into the customer’s team.
2. If Mapped tags is empty, add the customer-specific tag and save.
3. If a tag is mapped, sign in to rConfig and confirm at least one device carries that tag.
4. As a sanity check, click Test rConfig in System Settings → rConfig API to confirm the upstream is reachable.

Customer is missing one or two devices they expect to see

Cause: those devices don’t carry a tag mapped to the customer’s team.

Resolution: in rConfig, check the missing device’s tag list. Either add the customer’s tag to the device, or — if the customer is supposed to see all devices of a particular type — map an additional tag in Prism. Prevention: see the tag taxonomy guidance in Best Practices.

Customer sees devices that don’t belong to them

Cause: an over-permissive tag mapping (usually a broad tag like production or core).

Resolution: open the team’s tag mapping page, remove the broad tag, and add a customer-specific tag instead. Confirm the device list shrinks to the expected scope. This is a security incident — log it in your incident tracker and consider whether any sensitive configuration was viewed during the over-permissive window (the rConfig API request log captures every access).

API Connection and Brownouts

”Connection is down” landing page

Symptom: a customer reports a friendly “API Connection is down, please check back later” page when trying to view a configuration.

Cause: the upstream rConfig server is unreachable or returning errors, and the page in question is a non-cacheable single config body fetch.

Resolution:

1. Confirm the upstream is actually down (visit rConfig directly).
2. Check /admin/exception-logs for the underlying error.
3. Check /admin/rconfig-api-logs for the failure pattern.
4. If the upstream is back, the page should work on retry. If it’s still down, the customer can use list views (devices, configs list) which fall back to last-good cache while you investigate.

”Data may be out of date” badge

Symptom: customer reports a yellow badge with a stale timestamp on the dashboard or device list.

Cause: Prism’s hot cache missed and the live request to rConfig failed. Prism is serving the last-good cache to keep the portal usable.

Resolution: if the upstream is briefly unreachable (network blip, rConfig restart), the badge will clear automatically once the next request succeeds. If the badge persists for hours, treat it as an actionable signal: check the upstream, the network path, and the API logs.

Test rConfig button reports failure

Symptom: in System Settings → rConfig API, clicking Test rConfig returns an error.

Common causes and fixes:

• Wrong base URL — must be scheme://host[:port] only, no path. The form rejects paths but it’s worth re-checking.
• Wrong API token — copy/paste error or token revoked. Re-issue from rConfig and re-save.
• TLS certificate issue — the certificate is self-signed or the chain doesn’t validate. Either fix the certificate (preferred) or temporarily disable TLS verification while you debug. Re-enable verification before going to production.
• Network path — Prism can’t reach rConfig at all. Test from the Prism host with curl https://rconfig.example.com/api/v2/dashboard/health-latest -H 'apitoken: ...'.
• rConfig down — sign in to rConfig directly and confirm it’s healthy.

Time widget shows a clock divergence warning

Symptom: the sidebar clock popover shows Prism and rConfig with different wall-clock times.

Cause: one (or both) of Prism and rConfig has an NTP configuration issue.

Resolution: confirm NTP is running on both hosts. A divergence of more than a second suggests at least one host’s clock is drifting; sustained divergence suggests NTP isn’t running at all. Drifted clocks affect TOTP enrollment, audit timestamps, and TLS certificate validity — it’s worth fixing promptly.

Mail Delivery

Test email button reports success but nothing arrives

Cause: the test email was queued successfully but the queue worker isn’t running, or the relay is silently rejecting messages.

Resolution:

1. Confirm the queue worker is running (/horizon shows recent activity, or ps aux | grep queue:work).
2. Check /admin/exception-logs for SMTP-related errors.
3. Confirm the recipient inbox isn’t filtering or quarantining.
4. Try a different recipient address (an external Gmail or Outlook is a useful sanity check).

Mail goes out but lands in customer spam folders

Cause: the relay’s authentication (SPF, DKIM, DMARC) isn’t aligned with the sender domain.

Resolution: this is a relay/DNS configuration issue, not a Prism issue. Confirm:

• The from address’s domain has an SPF record listing your relay.
• DKIM signing is enabled on the relay and the public key is published in DNS.
• DMARC is set to p=none or higher, with reporting enabled.

A passing dig +short txt _dmarc.example.com plus a clean Gmail “show original” header analysis is the goal.

Exception alert emails not arriving

Cause: exception alerts are disabled, the recipient address is wrong, the throttle has suppressed recent alerts, or the underlying mail pipeline is broken.

Resolution:

1. Open System Settings → Exception Alerts.
2. Confirm Enabled is on.
3. Confirm the To address is correct.
4. Confirm the HTTP status filter actually matches the exception in question.
5. Click Send test exception alert. If the test doesn’t arrive, the underlying mail pipeline is broken — see “Test email button reports success but nothing arrives” above.

Branding

Logo upload rejected

Symptom: uploading an SVG logo fails with an “asset rejected” error.

Cause: Prism runs uploads through an SVG sanitiser that rejects external references, embedded scripts, and other unsafe content.

Resolution: re-export the SVG from your design tool with “no scripting” / “presentation attributes only” / “embed images” options. If the issue persists, upload a PNG or JPG instead — the sanitiser only applies to SVG.

Brand changes not appearing

Symptom: saved a brand setting but the portal still shows the old value.

Cause: browser cache (most common), or the per-team override is masking your global change.

Resolution:

1. Hard-refresh the browser (Cmd+Shift+R / Ctrl+Shift+R).
2. If you’re testing as a customer, confirm whether per-team branding is enabled and whether the team has its own override values that take precedence.
3. Confirm the change was actually saved (the save bar should show “Saved.”).

Per-team brand override doesn’t apply

Symptom: set a per-team brand value but the customer’s portal still shows the global brand.

Cause: Enable per-team branding is off at the instance level. The global toggle gates the per-team feature; without it, per-team rows are saved but ignored.

Resolution: open /admin/brand-settings and enable per-team branding. Customer portals will start picking up overrides on their next page load.

Onboarding Checklist

A task won’t auto-complete even though I’ve done the work

Cause: the auto-complete check looks at a specific signal (e.g. mail_host is non-empty for the mail-server task). If the field is technically populated but in an unexpected state, the check may not fire.

Resolution: open the relevant settings page and save again (even without changes). That triggers the relevant observer, which re-evaluates the task.

If the task still won’t auto-complete, you can mark it manually from the checklist UI — the dashboard celebrates progress regardless of whether tasks were observed or manually ticked.

Checklist disappeared

Cause: the checklist auto-collapses when all tasks are complete, and operators can also dismiss it.

Resolution: open the sidebar’s Onboarding entry to restore the checklist view at any time.

Performance

Portal pages are slow

Cause (most common): rConfig is responding slowly, the cache hit rate has dropped, or the Prism host is under-provisioned.

Resolution:

1. Open /admin/rconfig-api-logs and check the response time column for recent requests. Sustained 1000ms+ means the upstream is the bottleneck.
2. Check the cache hit/miss column. Hit rate should be 70–95% in steady state.
3. Open /admin/optimization and confirm the PHP runtime settings are still in production-ready state. Opcache disabled or memory limit too low can both cause sudden slowdowns.
4. If the host is under-provisioned (CPU pegged, swap in use), scale up the VM or process count.

A specific page is slow

Cause: the page may be hitting an uncached endpoint or fetching a large config body.

Resolution: narrow /admin/rconfig-api-logs by endpoint and look for the slow path. Single config body fetches scale with config size — a 30 MB config will take longer than a 30 KB one. Cache TTL tuning may help.

Security and Audit

Repeated permission denials in access audit

Symptom: /admin/access-audit filtered to denials shows a steady stream from the same user or IP.

Cause: confused user, misconfigured tag mapping, or someone probing.

Resolution:

• If a single user, message them to confirm what they were trying to do — usually it’s a workflow misunderstanding.
• If a single IP that’s not from a user you recognize, treat as an attempted intrusion and consider geo-blocking or WAF rules.

Audit log filling up

Symptom: the database is growing unexpectedly fast, traceable to the audit log table.

Cause: action volume has scaled past the retention window, or auto-purge has been disabled.

Resolution: open System Settings → Audit Retention and confirm the retention days are set to a finite value. Manual bulk-purge by date range from /admin/audit-log for one-off cleanup. If you genuinely need permanent retention, export to an external archive on a schedule.

When to Open a Support Ticket

Most Prism issues fall into one of the categories above. Open a ticket when:

• A symptom doesn’t match anything on this page or in /admin/docs/troubleshooting.
• A documented resolution doesn’t work.
• You suspect a Prism bug (a 500 error with a stack trace pointing at Prism code, not your config).
• You’ve experienced data loss or corruption.

See Support for how to reach the rConfig support team and what to include in the ticket.

Related Documentation

• Admin Guide — Day-to-day operations.
• Best Practices — Operational recommendations that prevent many of these issues.
• FAQ — Common questions.
• Support — How to get help.