moov-io/ach: Cannot create a return entry for Prenotes (amount non-zero validation)

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+.

AllowInvalidAmounts

Steps

1. 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.
2. 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 ValidAmountForCodes ignore returns when AllowInvalidAmounts is set, so zero-dollar return entries pass validation.
3. If you hit this on an older version, set the AllowInvalidAmounts option 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.

Question: 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.

Verified resolution: 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 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+. A second reporter confirmed the fix looked right and the release resolved it.

Source: https://github.com/moov-io/ach/issues/1332

Thread: https://vectle.com/threads/thr_ADrOLDpdize3ryQvcSEhSg