Troubleshooting

This guide covers common issues you may encounter with the SCF Controls Platform and their solutions.

Quick Diagnostics

Before diving into specific issues, check these common areas:

1. Browser console - Open DevTools (F12) and check the Console tab for errors
2. Network tab - Check for failed API requests
3. Clear cache - Hard refresh with Ctrl+Shift+R (Windows) or Cmd+Shift+R (Mac)

---

Authentication Issues

Google Sign-In Not Working

Symptom: “Sign in with Google” button does nothing or shows an error.

Check browser console for errors.

Common causes:

Error	Solution
popup_closed_by_user	User closed popup — retry
invalid_client	Contact support — OAuth configuration may need updating
Origin not allowed	Contact support — your domain may not be authorised
idpiframe_initialization_failed	Clear browser cookies, disable ad blocker

Sign-In Popup Closes Immediately

Cause: The popup was closed before completing authentication.

Solution: Try again and wait for the Google sign-in screen to fully load before selecting your account.

”Popup Blocked” Message

Cause: Your browser is blocking the sign-in popup.

Solutions:

1. Look for a popup blocker icon in your browser’s address bar
2. Click it and allow popups for this site
3. Try signing in again

Users Can Sign In But See Errors

Symptom: User authenticates but sees empty pages or errors.

Check:

1. Browser console for JavaScript errors
2. Network tab for failed API requests
3. Ensure you’re using a supported browser (Chrome, Firefox, Safari, Edge)

RBAC Status

Role-based access control is not yet enforced. All authenticated users currently have full access regardless of assigned role.

---

Frontend Issues

Blank Page After Loading

Symptom: Frontend loads but shows blank white page.

Check browser console (F12 → Console).

Common causes:

Console Error	Solution
Failed to fetch	Check your internet connection, try refreshing
Unexpected token	Clear browser cache and refresh
Network errors	Check if you’re behind a VPN or firewall that may be blocking access

Try these steps:

1. Hard refresh: Ctrl+Shift+R (Windows) or Cmd+Shift+R (Mac)
2. Clear browser cache and cookies for this site
3. Try a different browser
4. Try incognito/private browsing mode

Changes Not Appearing

Symptom: Made changes but don’t see them in the app.

Solutions:

1. Wait for sync — The platform syncs every 30 seconds
2. Click refresh — Use the refresh button in the header
3. Hard refresh — Ctrl+Shift+R (Windows) or Cmd+Shift+R (Mac)
4. Check sync indicator — Look for “Synced X ago” in the header

API Errors in Console

Symptom: Network requests failing with 4xx/5xx errors.

Debug:

1. Open Network tab in browser DevTools
2. Find the failing request
3. Check the response body for error details
4. If errors persist, contact support with the error details

---

Data Issues

Data Not Loading

Symptom: Pages show “Loading…” indefinitely or display no data.

Solutions:

1. Check your internet connection
2. Refresh the page — Click the refresh button or hard refresh
3. Check if the service is operational — Visit the platform status page if available
4. Clear browser cache — May resolve stale data issues

Data Sync Issues

Symptom: Changes made by one user not appearing for another.

How synchronisation works:

• The platform auto-syncs every 30 seconds
• Focus events (switching back to the tab) trigger immediate refresh
• Manual refresh button forces immediate sync

If sync seems stuck:

1. Click the refresh button in the header
2. Hard refresh the browser page
3. Sign out and sign back in

Missing Controls or Evidence

Symptom: Expected controls or evidence items not appearing.

Check:

1. Filters — Ensure no filters are hiding the items
2. Search — Clear any search terms
3. Organisation — Verify you’re in the correct organisation
4. Permissions — Confirm you have access to view the data

---

Performance Issues

Slow Page Loads

Symptom: Pages take > 3 seconds to load.

Solutions:

1. Check your internet connection — Run a speed test
2. Clear browser cache — Old cached data can slow things down
3. Reduce open tabs — Close unnecessary browser tabs
4. Try a different browser — Some browsers perform better than others
5. Disable browser extensions — Ad blockers or other extensions may interfere

Browser Becomes Unresponsive

Symptom: Browser freezes or becomes slow when using the platform.

Solutions:

1. Close other tabs — Free up browser memory
2. Hard refresh — Ctrl+Shift+R to reload the page
3. Restart browser — Close and reopen your browser
4. Check system resources — Close other applications if memory is low

---

Account Issues

Cannot Access Organisation

Symptom: Signed in but can’t see your organisation.

Solutions:

1. Check organisation selector — If you belong to multiple organisations, ensure the correct one is selected
2. Contact your admin — You may not have been added to the organisation yet
3. Verify email — Ensure you’re signed in with the correct Google account

Role-Related Questions

Current status: Role-based access control is informational only. All authenticated users have full access to all features regardless of assigned role.

Why roles exist: Roles are being tracked so that when RBAC is enforced in a future release, you won’t need to reconfigure users.

---

Browser Compatibility

Supported Browsers

The platform works best with:

Browser	Version
Chrome	Latest 2 versions
Firefox	Latest 2 versions
Safari	Latest 2 versions
Edge	Latest 2 versions

Known Limitations

• Internet Explorer — Not supported
• Very old browsers — May experience visual or functional issues
• Mobile browsers — Basic support; desktop recommended for full functionality

---

Self-Hosted Deployment Issues

These apply to the self-hosted Docker Compose stack only — see Deployment.

Dashboard Is Empty on a Fresh Deploy

Symptom: The stack starts and you can sign in, but the control library, frameworks, and dashboards are all empty. It looks broken.

Cause: The SCF catalogue has not been imported yet. The open-source build ships the importer, not SCF’s licensed content, so a fresh install starts with an empty catalogue.

Fix: Open the app — on a fresh install it shows a catalogue onboarding screen; upload your SCF .xlsx there and it is seeded live. (Upload requires single-tenant mode and a platform admin.)

For a scripted or air-gapped install you can instead seed it before first boot with the headless importer:

docker compose --profile init run --rm catalog-importer

docker compose up Warns About Unset Variables

Symptom: Bringing the stack up prints variable is not set warnings, or services fail to start.

Cause: No .env file. The compose file interpolates values that live in .env.

Fix: Copy the template before starting:

cp .env.example .env

Then edit the REQUIRED values (DB_PASSWORD, API_KEY) and bring the stack back up.

500 on First Write, or Risk Register Spins Forever

Symptom: Creating a system/risk returns a 500, or the Risk Register loads indefinitely on a fresh org.

Cause: Older builds before the single-tenant audit/auth fixes. The static API key had no backing user row (audit writes failed), and the risk register retried the failing create in a loop.

Fix: Update to a current release and ensure OSS_SINGLE_TENANT=1 is set. Recent versions seed a service-account user and pin the master key’s admin grant to your one organisation, so audited writes succeed.

Cross-Tenant Admin / Security Warning at Startup

Symptom: Logs show OSS_SINGLE_TENANT was disabled, or a logger.critical about ENVIRONMENT=development.

Cause (by design): OSS_SINGLE_TENANT is fail-closed — it refuses to grant the master key admin if more than one organisation or human member exists, to avoid a cross-tenant admin hole. ENVIRONMENT=development weakens error handling and must not run on a network-exposed host.

Fix: Keep a self-hosted deployment to a single organisation, leave ENVIRONMENT=production (the default), and only enable development on a trusted local machine.

Evidence Upload Fails

Symptom: Uploading an evidence file errors, or the download link does not resolve.

Cause: Object storage misconfiguration. By default the stack uses the bundled MinIO; the browser-facing presign endpoint must be reachable from your machine.

Fix: Confirm the AWS_* / EVIDENCE_* block in .env matches your chosen backend. For bundled MinIO, EVIDENCE_PUBLIC_ENDPOINT must be a host the browser can reach (e.g. http://localhost:9000). See Deployment → Evidence storage.

---

Getting Help

If you can’t resolve an issue:

1. Check the FAQ: See the FAQ for common questions

2. Contact Support:

   • Email: support@scfcontrolsplatform.com
   • Include: Browser type, error messages, steps to reproduce

3. Documentation:

   • Review relevant guides in this documentation
   • Check for any service status announcements

---

Related Guides

• Authentication — Sign-in help
• User Management — Managing users and roles
• FAQ — Frequently asked questions