Skip to main content

Troubleshooting (Decision Tree)

Use this format during an incident: Symptom → Possible Cause → Check Steps → Fix.

1) Symptom: API return 403 Forbidden​

Possible cause:

  • The user role does not match the access:* middleware.
  • The related entity has been soft-delete.

Check steps:

  1. Check the user role in the DB.
  2. Check the route endpoint middleware.
  3. Check soft-delete related entities.

Example verification query:

SELECT id, role FROM users WHERE id = :user_id;
SELECT id, deleted_at FROM projects WHERE id = :project_id;

Fix:

  • Correction of role-permission mapping.
  • Restore soft-delete data if it should be active.

2) Symptom: PO cannot update to certain status​

Possible cause:

  • Status transition rules limit per role.
  • Payload status is invalid.

Check steps:

  1. Check the role of the user who did the update.
  2. Check the current PO state.
  3. Check the validator status in the service/controller.

Example verification query:

SELECT id, status, updated_at FROM purchase_orders WHERE id = :po_id;

Fix:

  • Adjust role/flow transitions in code.
  • If a new state is added, update the state machine + validator.

3) Symptoms: SPB cannot be changed​

Possible cause:

  • SPB status is approved and system locked.

Check steps:

  1. Retrieve current SPB status.
  2. Check the last change request log.

Example verification query:

SELECT id, status, approved_at FROM spb WHERE id = :spb_id;

Fix:

  • Follow the official revision flow (create revision entities if necessary).
  • Do not bypass the lock without senior approval.

4) Symptom: Push notifications are not sent​

Possible cause:

  • FCM token is invalid/expired.
  • Invalid Firebase credentials.
  • Queue worker is not running.

Check steps:

  1. Check the target user token.
  2. Check the FCM error log.
  3. Check the job queue.

Example verification query:

SELECT user_id, token, updated_at
FROM fcm_tokens
WHERE user_id = :user_id
ORDER BY updated_at DESC
LIMIT 5;

Fix:

  • Refresh FCM tokens.
  • Repair credentials.
  • Restart the worker once the root cause is clear.

5) Symptom: Export/PDF does not appear​

Possible cause:

  • Storage permission problem.
  • Job export failed.
  • PDF/Excel dependencies are incomplete.

Check steps:

  1. Check the job export log.
  2. Check the resulting file in storage.
  3. Check the queue status.

Fix:

  • Fix directory permissions.
  • Retry jobs that are safe to repeat.
  • Make sure the dependency is installed.

6) Symptom: Payment stuck at waiting_confirmation​

Possible cause:

  • The approve/verify stage has not been executed in the correct role.
  • Payment status transition rules are on hold.

Check steps:

  1. Check the payment approval history.
  2. Check the last actor's role.

Example verification query:

SELECT id, status, approved_by, verified_by, updated_at
FROM payments
WHERE id = :payment_id;

Fix:

  • Complete the approval stages according to the role matrix.
  • Fix transition rules if there are bugs.

7) Symptom: Migration error when deploying​

Possible cause:

  • Existing schema conflict.
  • Legacy data is not compatible with new constraints.
  • Locking/timeout during migration.

Check steps:

  1. Check failed migration + SQL error details.
  2. Check the data condition before the constraints are applied.
  3. Check the duration/lock query in the DB.

Example verification query:

-- contoh: cek data yang melanggar NOT NULL baru
SELECT COUNT(*)
FROM target_table
WHERE target_column IS NULL;

Fix:

  • Apply an expand/contract approach.
  • Run backfill first before tight constraints.
  • If impact is large: rollback according to playbook.

Quick Triage Flow​

Notes​

  • The query table/column names above may differ between environments: requires verification with actual schema.