AI AI Workforce OS v1.0.0

Troubleshooting

Common problems, error messages, and how to resolve them.

All usersSystem Administrators

Overview#

This page collects the most common real problems users hit, most of which are configuration or expectation gaps rather than bugs — each links to the module page with more detail.

Purpose#

Give a fast path from symptom to explanation and fix, without needing to know which module owns the issue first.

Step-by-Step Instructions#

Login and access#

  1. Cannot log in at all: confirm your account was provisioned with the correct work email; if your organization uses SSO, sign in through your identity provider rather than a password form.
  2. Locked out after failed attempts: the system enforces a configurable lockout threshold and duration. Wait out the lockout window or contact your System Administrator to reset it.
  3. Lost my MFA device: use a saved recovery code to sign in, then re-enroll a new authenticator. See Security.

Attendance, leave, and payroll#

  1. No GPS/biometric clock-in option: not implemented in this release. See Attendance.
  2. Leave balance looks wrong after year-end: check the leave policy’s carry-forward cap and expiry. See Leave.
  3. Payslip missing tax deductions: expected — no statutory tax engine ships in this release. See Payroll.
  4. No "Run Payroll" button in HR Admin: expected — that screen is read-only in this release. See Payroll.

Integrations and mobile#

  1. Connected Google/Microsoft/Slack integration is not syncing data: expected — connection works, scheduled sync is a documented gap. See Integrations.
  2. Push notifications never arrive: most likely your administrator has not configured Web Push/FCM credentials. See Mobile App.
  3. No app in the app store: expected — the product is a PWA, installed from your browser. See Mobile App.

API and deployment#

  1. 401 Unauthorized on API calls: confirm your API key/OAuth token is valid and formatted as documented at /docs. See Public API.
  2. API container fails to start: confirm PostgreSQL and Redis are reachable and healthy first. See Installation.
  3. Web app loads but API calls fail: check NEXT_PUBLIC_API_URL and CORS_ORIGIN alignment. See Installation.

Common Mistakes#

  • Assuming a gap noted in this documentation (like payroll tax calculation or integration sync) is a bug rather than the documented current state of the release.
  • Not checking whether an issue is a permissions/role problem before escalating it as a system error.

Troubleshooting#

The issue I’m seeing isn’t listed here.#

Check the specific module’s page — each one has its own Troubleshooting section with more detail than fits here. If it’s still unresolved, contact your System Administrator with the exact error message and the screen you were on.

FAQSecurityInstallation

FAQ#

Who do I contact if this page doesn’t solve my problem?

Your organization’s System Administrator or HR Administrator, depending on the area affected. They have access to logs and configuration this documentation cannot see.

Best Practices#

  • Before reporting an issue, check whether it matches a documented "Not Available" item on the relevant module page — many "bugs" are gaps documented here.
  • Include the exact error message, the screen/URL, and your role when escalating an issue.