# Integrated Payroll Files Errors

Updated Mar. 24, 2026

**Overview**

If a payroll from your integrated payroll provider (Rippling, Paylocity, TriNet, or Gusto) is failing, rejected, or not processing correctly, use this guide to identify and resolve the issue.

**Time-sensitive:** Check the payroll effective date immediately. If it's approaching or has passed, contact Betterment support right away for priority assistance.

**Step 1: Gather Key Details First**

Before troubleshooting, collect the following information:

- Payroll provider name (Rippling, Paylocity, TriNet, or Gusto)
- Your company ID
- Payroll effective date
- Current payroll status shown in your Betterment admin portal (pending, failed, rejected, or canceled)

**Step 2: Identify the Symptom**

Review the symptom you're experiencing and follow the corresponding next step:

|     |     |     |
| --- | --- | --- |
| **Symptom** | **Likely Cause** | **Next Step** |
| "Approved but not finalized yet" appears in your dashboard | Payroll is still open in your payroll provider | Go to Step 4 |
| File rejected due to disallowed source | A contribution source was removed from your plan but is still in the payroll file | Go to Step 3 |
| Some employees are missing from the file | Employee ID or mapping mismatch between systems | Go to Step 3 |
| Employer match calculation is incorrect | Mismatch in match formula setup (% of contribution vs. % of compensation) | Go to Step 3 |

**Step 3: Review Plan Configuration vs. File Contents**

Compare your plan design in Betterment to what's coming through from your payroll provider. Check for the following:

- Contribution sources match — No removed sources are still present in the payroll file
- Safe harbor type is correct
- Match formula aligns — Confirm whether the match is based on % of compensation or % of contribution
- Effective dates are accurate
- Deduction codes in your payroll provider match what Betterment expects

What to Do Based on Your Findings

|     |     |
| --- | --- |
| **Finding** | **Action** |
| Configuration mismatch found | Update your plan configuration with Betterment support, OR work with your payroll provider to adjust deduction codes or contribution sources. Then resubmit the payroll. |
| Missing employees or incorrect employee ID mapping | Work with your payroll provider to correct employee ID mapping and rerun the payroll. |
| No mismatch found | Move to Step 4 to verify the payroll has been finalized in your provider system |

**Step 4: Confirm Finalization Status with Your Payroll Provider**

Many processing issues occur because Betterment attempts to pull a payroll that hasn't been finalized yet.

Check: Is the payroll fully finalized and closed in your payroll provider system?

_Note: This is especially common with Rippling. Make sure the payroll run is fully approved and closed before expecting Betterment to process it._

What to Do Based on the Status

|     |     |
| --- | --- |
| **Scenario** | **Action** |
| Payroll not yet finalized in the provider | Wait until you finalize the payroll in your provider system, then check Betterment again |
| Payroll was corrected or rerun in the provider | Confirm your provider generated a new file. Contact Betterment support to verify the updated file has been retrieved. |
| Payroll is finalized but still failing | Configuration and provider setup are not the issue — proceed to Step 5 to contact support |

**Step 5: If needed, contact Betterment Support**

If the payroll is finalized in your provider, your plan configuration is correct, and the file is still failing to process, please contact Betterment support with the following information:

|     |     |
| --- | --- |
| **Information Needed** | **Your Details** |
| Company ID |  |
| Payroll ID (if available) |  |
| Payroll provider name |  |
| Full error message text |  |
| Names of affected employees (1-2 examples) |  |
| Steps you've already completed |  |

Providing this information upfront will help our team resolve the issue more quickly.