Error Codes Reference

This page documents validation errors that rledger check can report.

Error Format

Errors are displayed as:

file.beancount:42: error[E1001]: Account not opened

Format: file:line: error[code]: message

Error Code Categories

Range	Category
E1xxx	Account errors
E2xxx	Balance errors
E3xxx	Transaction errors
E4xxx	Booking/lot errors
E5xxx	Currency errors
E6xxx	Metadata errors
E7xxx	Option errors
E8xxx	Document errors
E10xxx	Date warnings/info

Account Errors (E1xxx)

E1001: Account Not Opened

Cause: Transaction uses an account without an open directive.

Example:

; No 'open' for Expenses:Food
2024-01-15 * "Coffee"
  Expenses:Food   5.00 USD
  Assets:Cash    -5.00 USD

Fix: Add an open directive:

2020-01-01 open Expenses:Food
2020-01-01 open Assets:Cash  USD

Or use rledger doctor missing-open to generate them.

E1002: Account Already Open

Cause: Duplicate open directive for same account.

Fix: Remove the duplicate open directive.

E1003: Account Used After Close

Cause: Transaction on an account after its close date.

Example:

2024-01-01 close Assets:OldBank

2024-02-15 * "Late transaction"
  Assets:OldBank   100.00 USD   ; Account is closed

Fix: Use correct account or adjust close date.

E1004: Account Close With Non-Zero Balance

Cause: Closing an account that still has a balance.

Fix: Zero out the account balance before closing.

E1005: Invalid Account Name

Cause: Account name doesn't match required format.

Example:

2024-01-15 * "Coffee"
  expenses:food   5.00 USD    ; Lowercase not allowed

Fix: Use Title:Case:Accounts starting with Assets, Liabilities, Equity, Income, or Expenses.

Balance Errors (E2xxx)

E2001: Balance Assertion Failed

Cause: Account balance doesn't match assertion.

Example:

2024-01-15 balance Assets:Checking  1000.00 USD
; But actual balance is 950.00 USD

Fix:

1. Check for missing transactions
2. Verify the expected amount
3. Use rledger doctor context to see surrounding transactions

E2002: Balance Exceeds Tolerance

Cause: Balance is off by more than the allowed tolerance.

Fix: Adjust the balance assertion or find the discrepancy.

E2003: Pad Without Balance Assertion

Cause: A pad directive has no subsequent balance assertion.

Fix: Add a balance assertion after the pad.

E2004: Multiple Pads for Same Balance

Cause: Multiple pad directives for the same balance assertion.

Fix: Remove duplicate pad directives.

Transaction Errors (E3xxx)

E3001: Transaction Does Not Balance

Cause: Postings don't sum to zero.

Example:

2024-01-15 * "Coffee"
  Expenses:Food    5.00 USD
  Assets:Cash     -4.00 USD   ; Doesn't balance

Fix: Ensure postings sum to zero:

2024-01-15 * "Coffee"
  Expenses:Food    5.00 USD
  Assets:Cash     -5.00 USD

E3002: Multiple Missing Amounts

Cause: More than one posting is missing an amount for the same currency.

Fix: Only one posting per currency can have an inferred amount.

E3003: Transaction Has No Postings

Cause: Transaction has no posting lines.

Fix: Add at least two postings to the transaction.

E3004: Transaction Has Single Posting (Warning)

Cause: Transaction has only one posting line.

Fix: Add a second posting to complete the transaction.

Booking Errors (E4xxx)

E4001: No Matching Lot

Cause: Can't find a lot to reduce when selling/removing inventory.

Example:

2024-01-15 * "Sell AAPL"
  Assets:Brokerage  -10 AAPL {150.00 USD}  ; No lot at this cost

Fix: Check cost basis matches existing lot, or use {} for automatic matching.

E4002: Insufficient Units

Cause: Trying to reduce more units than available in the lot.

Fix: Check the quantity being sold matches available holdings.

E4003: Ambiguous Lot Match

Cause: In STRICT booking mode, multiple lots could match.

Fix: Specify the exact lot using cost basis {cost} or date {date}.

E4004: Negative Inventory

Cause: Reduction would create negative inventory.

Fix: Check that you have sufficient holdings before selling.

Currency Errors (E5xxx)

E5001: Currency Not Declared

Cause: Using a currency without a commodity directive (when strict mode enabled).

Fix: Declare the currency:

2020-01-01 commodity USD

E5002: Currency Not Allowed in Account

Cause: Posting uses currency not allowed for account.

Example:

2020-01-01 open Assets:Bank  USD  ; Only USD allowed

2024-01-15 * "Deposit"
  Assets:Bank    100.00 EUR       ; EUR not allowed

Fix: Use allowed currency or update account declaration.

Metadata Errors (E6xxx)

E6001: Duplicate Metadata Key

Cause: Same metadata key used twice on one directive.

Fix: Remove the duplicate key.

E6002: Invalid Metadata Value

Cause: Metadata value has wrong type.

Fix: Use correct value type (string, number, date, etc.).

Option Errors (E7xxx)

E7001: Unknown Option

Cause: Unrecognized option name.

Fix: Check option spelling. Use rledger doctor list-options to see valid options.

E7002: Invalid Option Value

Cause: Option value is invalid.

Fix: Check the expected format for the option.

E7003: Duplicate Option

Cause: Non-repeatable option specified multiple times.

Fix: Remove duplicate option directives.

Document Errors (E8xxx)

E8001: Document Not Found

Cause: Document directive references missing file.

Fix: Ensure file exists at specified path.

Date Warnings (E10xxx)

E10001: Date Out of Order (Info)

Cause: Entries are not in chronological order.

Note: This is informational only and does not prevent validation.

E10002: Entry Dated in Future (Warning)

Cause: Entry has a date in the future.

Note: This is a warning that may indicate a typo.

Using Error Information

Find Context

# See what's around an error
rledger doctor context ledger.beancount 42

Check Specific Account

# View account history
rledger query ledger.beancount \
  "SELECT date, narration, position WHERE account = 'Assets:Bank' ORDER BY date"

Generate Missing Opens

# Auto-generate open directives
rledger doctor missing-open ledger.beancount

See Also

• check command - Running validation
• doctor command - Debugging tools
• Plugins - Plugin-specific errors