Budget Troubleshooting

This guide covers common budget issues and their solutions.

Budget Assignment Issues

User doesn't have expected budget

Symptoms:

• User sees "no budget" when booking
• User has a different budget than expected

Diagnostic steps:

1. Check user-level assignment:

   • Is there a direct user assignment?
   • Is it within the effective date range?
   • Is the assigned budget active?

2. Check role-level assignment:

   • What role does the user have?
   • Is that role assigned a budget?
   • Is the role's budget active?

3. Verify budget status:

   • Is the budget active (isActive: true)?
   • Is the budget not deleted (deletedAt: null)?

Solutions:

User override not working

Symptoms:

• User has a user-level assignment but gets role budget

Causes:

• User assignment is outside effective dates
• Assigned budget is inactive or deleted

Solution: Check the effective dates and budget status:

User Assignment:
  Budget: VIP Travel
  Effective From: 2024-01-01
  Effective Until: 2024-03-31  ← Check if expired
  Budget Status: Active ← Check this

Role assignment affects wrong users

Symptoms:

• Users who shouldn't have a budget do
• Users who should have it don't

Solution: Verify user role assignments:

Expected: All "Manager" users get "Manager Budget"

Check:
1. Which users have the "Manager" role?
2. Is "Manager Budget" assigned to "Manager" role?
3. Do affected users have user-level overrides?

Budget Amount Issues

Budget shows wrong remaining amount

Symptoms:

• Remaining doesn't match expected
• User can't book even though they should have budget

Causes:

1. Pending reservations reducing available
2. Currency conversion affecting amounts
3. Shared pool with other users spending

Diagnostic steps:

1. Check pending amount:

   Total: $5,000
   Spent: $2,000
   Pending: $1,500  ← This reduces remaining
   Remaining: $1,500

2. Check for abandoned bookings:

   • Old pending reservations may be blocking budget
   • They should timeout automatically (default 72 hours)

3. For shared pools, check other users:

   • Other users may have spent or reserved

Solutions:

Rollover not appearing

Symptoms:

• Expected rollover from previous period not applied
• New period starts with base amount only

Causes:

1. Rollover policy is "None"
2. Previous period had no remaining balance
3. Rollover job hasn't run yet
4. Rollover hit maximum cap

Diagnostic steps:

1. Check rollover policy:

   Budget settings:
     Rollover Policy: None  ← No rollover expected

2. Check previous period remaining:

   Previous Period:
     Spent: $5,000
     Remaining: $0  ← Nothing to roll over

3. Check for timing:

   • Rollover processes daily
   • New period may not have rollover yet

4. Check maximum cap:

   Max Rollover: $1,000
   Previous Remaining: $2,000
   Rollover Applied: $1,000 (capped)

Enforcement Issues

Booking blocked unexpectedly

Symptoms:

• User can't complete booking
• Error says "insufficient budget"

Causes:

1. Enforcement mode is "Block"
2. Budget is actually exceeded
3. Pending reservations consuming budget

Solutions:

1. Verify enforcement mode:

   • If Block, user cannot exceed budget
   • Consider changing to Warn or Require Approval

2. Check actual availability:

   Total: $5,000
   Spent: $4,000
   Pending: $800
   Remaining: $200
   Booking: $500
   Shortfall: $300

3. Release stale pending:

   • Cancel abandoned bookings
   • Wait for timeout

Warning not appearing

Symptoms:

• User exceeds budget but sees no warning
• Expected enforcement not happening

Causes:

1. Enforcement mode is "Track Only"
2. User doesn't have a budget assigned
3. Booking is within budget

Diagnostic:

Check budget resolution:
  User has budget: Yes
  Enforcement mode: TRACK_ONLY  ← No warning for this mode
  
Or:
  User has budget: No  ← No budget to enforce

Approval not required

Symptoms:

• Expected booking request, but booking completed directly
• Over-budget booking went through

Causes:

1. Enforcement mode is not "Require Approval"
2. User doesn't have budget assigned
3. Booking was within budget

Solution: Verify budget settings:

Enforcement Mode: WARN_WHEN_EXCEEDED  ← Not Require Approval

Change to: REQUIRE_APPROVAL_WHEN_EXCEEDED

Period Issues

Period dates wrong

Symptoms:

• Period doesn't start/end when expected
• Misalignment with fiscal calendar

Causes:

• Period start day/month configuration
• Sequential period calculation from previous

Solution: Review period settings:

Period Type: Monthly
Start Day: 15  ← Periods run 15th to 14th

If you expected 1st to last:
  Change Start Day to: 1

New period not created

Symptoms:

• Old period shows as current
• Rollover hasn't happened

Causes:

• Rollover job hasn't run
• Budget is inactive
• Technical issue

Diagnostic:

• Check if rollover job ran (logs/monitoring)
• Verify budget is active
• Check for error logs

Solution:

• Wait for next scheduled run
• Contact administrator if persists

Transaction Issues

Transaction not appearing

Symptoms:

• Made a booking but don't see it in transactions
• Budget amounts not updated

Causes:

• Booking still in progress
• Payment not confirmed
• Different budget than expected

Solution:

1. Verify booking status (pending vs confirmed)
2. Check which budget the booking was against
3. Wait for booking to fully process

Refund not crediting budget

Symptoms:

• Received refund but budget not increased
• Refund shows but remaining unchanged

Causes:

• Company setting: creditRefundsToBudget = false
• Refund went to different period
• Technical processing delay

Solution:

1. Check company settings for refund behavior
2. Check which period received the credit
3. Wait for processing if recent

Common Error Messages

"Budget not found"

Cause: The referenced budget doesn't exist or is deleted.

Solution:

• Verify budget ID
• Check if budget was deleted
• Recreate assignment if needed

"No active budget period found"

Cause: Budget exists but has no active period.

Solution:

• Period should be auto-created
• Check if budget was just created
• Contact administrator

"Budget already reserved for reference"

Cause: Duplicate reservation attempt for same booking.

Solution:

• Previous reservation exists
• Either complete or cancel the existing booking
• Wait for timeout if abandoned

"User already has a budget assignment"

Cause: Trying to add second user assignment.

Solution:

• Each user can only have one direct assignment
• Edit existing assignment instead of creating new
• Or remove old before adding new

"Cost center code already exists"

Cause: Duplicate cost center code in company.

Solution:

• Use unique code
• Check existing cost centers for conflicts

Performance Issues

Budget checks slow

Symptoms:

• Booking flow sluggish during budget check
• Timeout during evaluation

Causes:

• Large transaction history
• Complex resolution queries
• Database performance

Solutions:

• Check database indexes
• Review transaction volume
• Contact technical support

Quick Diagnostic Checklist

When budget issues occur, run through this checklist:

Getting Help

If you can't resolve an issue:

1. Gather information:

   • User ID and email
   • Budget name and ID
   • Expected vs actual behavior
   • Screenshots if applicable
   • Timestamp when issue occurred

2. Check recent changes:

   • Budget configuration changes
   • Assignment changes
   • Company settings changes
   • User role changes

3. Contact administrator:

   • Provide gathered information
   • Describe steps to reproduce
   • Note when issue started
   • Include any error messages verbatim

Related Topics

• Budget Resolution - How budgets are assigned
• Enforcement Modes - How enforcement works
• Monitoring - Track and diagnose issues