Skip to content

Troubleshooting and Runbook

Authentication and Portal Context

Symptom

  • The portal stays on an authentication interstitial.
  • The user signs in successfully but is redirected to /forbidden.
  • The org console shows missing-org-context.

Checks

  1. Verify the correct portal URL and Keycloak client are in use.
  2. Distinguish identity failures from context failures.
  3. For password-grant verification, use: curl -s -X POST 'https://auth.test.emali2.damplabs.com/realms/emali2/protocol/openid-connect/token' -H 'Content-Type: application/x-www-form-urlencoded' --data-urlencode 'grant_type=password' --data-urlencode 'client_id=emali2-cli' --data-urlencode 'username=<user>' --data-urlencode 'password=<password>'
  4. If the org console redirects to /forbidden?reason=missing-org-context, confirm the account resolves to a live organization and has assigned units where required.
  5. During this refresh on 2026-03-25, customer1, admin1, and sp-finance authenticated successfully, while the previously documented seeded org users did not. Treat that as a live test-environment drift, not as intended product behavior.

Customer Loan Issues

Symptom

  • The loans page shows a current loan but the repayment panel does not behave as expected.
  • A repayment amount larger than the balance due seems to post only partially.
  • The page rejects repayment because no wallet is selected or because the balance is too low.

Checks

  1. Confirm the customer is on /app/loans and that a platform loan with a local loan ID is selected.
  2. Verify the repayment request includes walletId.
  3. Confirm the selected wallet balance is at least the amount the system can actually apply right now.
  4. Expect the platform to cap the applied amount to the loan's outstanding balance. Excess value should remain in the wallet and be described back to the customer in the success message.
  5. If the customer has an active loan, new offers are intentionally secondary to the servicing experience.

Agent Hierarchy and Child-Agent Routes

Symptom

  • /app/agents/:agentId/children returns an error or shows no child agents.
  • A supposed super agent has no hierarchy action on the detail page.

Checks

  1. Confirm the agent is tier SUPER or MASTER.
  2. Verify the hierarchy endpoint directly: curl -s 'https://api.test.emali2.damplabs.com/api/v1/agents/<agentId>/hierarchy' -H "Authorization: Bearer <token>"
  3. To find live super agents in the admin environment, query: curl -s 'https://api.test.emali2.damplabs.com/api/v1/admin/agents?page=0&size=20&tier=SUPER' -H "Authorization: Bearer <token>"
  4. Remember that /app/agents in the service-provider portal is an alias route and not the primary list surface anymore.

Float Management and Unit Scope

Symptom

  • The organization float page shows empty balances or no transaction history.
  • Top-up and deposit actions appear disconnected from the selected unit.

Checks

  1. Confirm the signed-in user has assigned organization units.
  2. Verify the selected unit resolves to an agent-backed organization unit.
  3. Check the unit-scoped calls used by the page:
  4. GET /api/v1/organization-units/assigned
  5. organization journal report for the selected unitId
  6. organization-unit transaction search for the same unitId
  7. Treat float history as unit-scoped evidence. The page now pairs current balance with the selected unit's journal and transaction snapshot.

Service Provider Alias Confusion

Symptom

  • Opening /app/agents does not show the old standalone agent directory.
  • Opening /app/agents/:agentId renders a blank page in the current test deployment.

Checks

  1. This is expected. /app/agents now redirects to /app/organizations.
  2. If /app/agents/:agentId renders blank, open the browser console. During this refresh on 2026-03-25 the live admin bundle threw ReferenceError: Stack is not defined on that direct detail route.
  3. Use /app/agents/:agentId/children for child-agent hierarchy review while the direct detail rendering issue is being corrected.
  4. Use the organization surfaces to navigate into agents when you need the canonical admin entry point.

2FA Page Errors

Symptom

  • /app/security/2fa shows request errors or partial state.

Checks

  1. Verify the profile-security endpoints are deployed and routable from the gateway.
  2. Confirm the token and client are accepted by the identity-backed 2FA flows.
  3. Expect the portal to use the live identity service rather than a separate local 2FA store.

Docs Build and Versioning

Local Validation

  1. From emali2-docs/, run mkdocs build.
  2. Fix broken image references or malformed Markdown before building the image.
  3. Use the generated site/ output for local inspection.

Publish-Readiness

  1. The docs image build is versioned with DOCS_VERSION=dev.
  2. The current Docker workflow also moves the latest alias with that build.
  3. Use emali2-docs/scripts/build-image.sh when you need the mike-based image workflow exercised end to end.

Playwright Evidence Handling

  • Store raw capture artifacts under output/playwright/.
  • This refresh used output/playwright/refresh-20260325/.
  • Copy only stable screenshots into docs/assets/images/user-guides/.
  • Re-run portal-specific capture when auth or route behavior changes, especially for customer loans and agent hierarchy flows.