Troubleshooting Guide
Common issues and solutions for the Keshless Accounting System.
Quick Reference
| Issue | Likely Cause | Solution |
|---|---|---|
| Balance discrepancy | Missing journal entry | Run reconciliation |
| Trial balance not balanced | Incomplete journal | Find unbalanced entries |
| Duplicate journal entries | Race condition | Reverse duplicate |
| Entry stuck PENDING | Job not running | Check scheduler |
| Cannot modify entry | Entry is posted | Create reversal |
| Account not found | Wrong code | Verify account code |
| Session timeout | Long transaction | Increase timeout |
| Hash chain broken | Tampering | Alert security team |
Balance Discrepancies
Problem
Wallet balance doesn't match ledger balance.
Diagnosis
Run balance verification for the affected user/vendor to compare wallet vs ledger balances.
Solutions
| Discrepancy | Action |
|---|---|
| < E1.00 | Auto-correct small discrepancies (rounding) |
| E1.00 - E10.00 | Manual correction with admin approval |
| ≥ E10.00 | Full investigation required |
Investigation Steps
- Check audit log for tampering
- Verify all wallet transactions have journal entries
- Check for orphaned ledger entries
- Review recent manual adjustments
- Contact development team if unresolved
Trial Balance Not Balanced
Problem
Total debits ≠ Total credits in trial balance.
Common Causes
| Cause | Description |
|---|---|
| Incomplete journal | Created journal but transaction failed |
| Manual database edit | Direct data modification |
| Race condition | Concurrent updates without locking |
| Rounding errors | Accumulated floating-point issues |
Solution
Find and reverse unbalanced journal entries, then recreate correctly.
Duplicate Journal Entries
Problem
Same transaction has multiple journal entries.
Prevention
Always check for existing journal entry before creating a new one using the wallet transaction ID.
Solution
- Identify the duplicate
- Reverse the duplicate entry
- Update code to prevent duplicates
- Review concurrent request handling
Entry Stuck in PENDING
Problem
Journal entry not auto-posted after 30 minutes.
Common Causes
| Cause | Solution |
|---|---|
| Reconciliation job not running | Check job schedule |
| Entry flagged for manual review | Complete review |
| AML flag preventing auto-post | Clear AML review |
Solutions
- Check if daily reconciliation job is scheduled
- Run job manually if needed
- Manually post entry if appropriate
- Check for AML flags requiring review
Cannot Modify Posted Entry
Problem
Attempting to edit an immutable posted entry.
Explanation
Posted entries are immutable by design for audit compliance.
Solution
Create a reversing entry:
- Reverse the incorrect entry
- Create a new correct entry
- Both entries remain in audit trail
Account Not Found
Problem
Template references non-existent account code.
Diagnosis
Verify the account exists in Chart of Accounts.
Solutions
| Issue | Action |
|---|---|
| Wrong code | Use correct account code |
| Account doesn't exist | Create account if it should exist |
| Wrong template | Use correct template |
Database Session Timeout
Problem
Long-running transaction times out.
Solutions
| Solution | Description |
|---|---|
| Increase timeout | Extend session timeout |
| Split operations | Break into smaller transactions |
| Optimize queries | Add indexes, reduce lookups |
Hash Chain Broken
Problem
Audit log tampering detected.
CRITICAL: This indicates someone modified audit data.
Immediate Actions
- Freeze system immediately
- Alert security team
- Investigate: Who has database access? When did it occur?
- Restore from backup if tampering confirmed
- Implement stricter access controls
Performance Issues
Problem
Slow reconciliation or queries.
Solutions
| Solution | Description |
|---|---|
| Verify indexes | Ensure proper indexes exist |
| Use balance cache | Query AccountBalance, not LedgerEntry |
| Limit date ranges | Don't query all-time data |
| Batch operations | Process in smaller chunks |
Required Indexes
| Collection | Index Fields |
|---|---|
| LedgerEntry | journalId, accountCode + status, entityId + entityType |
| JournalEntry | walletTransactionId |
| AccountBalance | accountCode + currency |
Health Check
Run the accounting system health check to diagnose issues:
| Check | Description |
|---|---|
| Chart of Accounts | Verify accounts initialized |
| Trial Balance | Verify debits = credits |
| Recent Journals | Check for errors |
| Reconciliation Status | Check last run |
Prevention Best Practices
| Practice | Benefit |
|---|---|
| Always use database sessions | ACID compliance |
| Always use templates | Consistent entries |
| Run daily reconciliation | Catch discrepancies early |
| Monitor discrepancies | Set up alerts |
| Never modify database directly | Use services only |
| Test in development | Catch issues early |
| Review audit logs | Detect anomalies |
| Keep backups | Recovery capability |
Getting Help
If you can't resolve an issue:
- Run health check and note results
- Export diagnostic data (trial balance, recent journals, reconciliation status)
- Check audit logs for clues
- Contact development team with diagnostic data