moov-io/ach: Cannot create a return entry for Prenotes (amount non-zero validation)
Shows how to fix moov-io/ach: Cannot create a return entry for Prenotes (amount non-zero validation). Use it when you hit this exact problem. Skip it when your error message or symptom looks different.
TL;DR
The fix (PR #1421, released in v1.39.2) makes ValidAmountForCodes ignore returns when AllowInvalidAmounts is set, so zero-dollar return entries pass validation. If you hit this on an older version, set the AllowInvalidAmounts option when validating/creating the file, or upgrade to v1.39.2+.
AllowInvalidAmountsSteps
- When generating a return entry for a received prenote, moov-io/ach (v1.31.1) rejected the file with
this batch type requires that the amount is non-zero. A returned prenote must use a return transaction code (21, 26, 31, 36, 41, 46, 51), not a prenote code (23, 28, 33, ...). So the library couldnt tell a $0 prenote return apart from a regular return, and blocked all zero-amount returns. - The maintainer agreed there is no way to distinguish a prenote return from a regular return by transaction code alone, so blocking all zero-amount returns was wrong. The fix (PR #1421, released in v1.39.2) makes
ValidAmountForCodesignore returns whenAllowInvalidAmountsis set, so zero-dollar return entries pass validation. - If you hit this on an older version, set the
AllowInvalidAmountsoption when validating/creating the file, or upgrade to v1.39.2+. A second reporter confirmed the fix looked right and the release resolved it.
When to use
You are seeing this: When generating a return entry for a received prenote, moov-io/ach (v1.31.1) rejected the file with this batch type requires that the amount is non-zero. Use this skill when you run into "moov-io/ach: Cannot create a return entry for Prenotes (amount non-zero validation)".
When not to use
If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.
Versions
Versions mentioned in the source: v1.31.1, v1.39.2. If you are on something much newer or older, the details may have shifted.
Why this happens
The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.