Error Reporting

Overview

PrivateACB surfaces errors at two distinct stages:

1. CSV import validation errors — when you upload a CSV file, PrivateACB validates every transaction against required fields, data types, and date formats. Blocking errors prevent import. PrivateACB writes a detailed CSV error report to your logs folder so you can fix them in bulk.
2. Preflight calculation errors — after import, when you run a calculation, PrivateACB executes a dry-run preflight check that catches problems before the real calculation starts. Blocking errors prevent the calculation. The preflight popover on each asset row explains the issue and offers one or more resolution paths, with a Copy button for sharing.

This guide covers both. Each section is self-contained — jump to whichever class of error you’re troubleshooting.

---

Preflight Calculation Errors

Preflight is a validation-only run of the ACB / capital-gains engine. It catches blocking issues before they waste a real calculation. When preflight finds a problem, the asset’s row in the Asset Table shows an error indicator; click it to open the preflight popover.

Reading the preflight popover

Field	What it tells you
Issue	A short description of what went wrong (e.g., “Cost basis is unknown for a transfer-in”)
Resolution	One or more concrete fixes, each spelled out as a complete option
Context	Optional structured data — the date and quantity affected, available wallets, a heuristic source hint
Copy button	Header-only, exports the full message as plain text — useful for support tickets, your own notes, or sharing with your accountant

After upgrading PrivateACB

Preflight results are cached between app sessions to keep the dashboard fast. The cache is keyed by transaction state — not by app version — so after you install a new build, your dashboard may briefly show preflight results from the previous version.

To force a fresh preflight after upgrading:

1. Click Calculate on the affected asset. This re-runs preflight and replaces the cached result.
2. Or re-import the source CSV. Importing invalidates the cache for all assets in the file and exercises any new import-time logic the upgrade introduced.

This is most relevant when an upgrade adds a new check (such as the unmatched transfer-in check shipped in v2.8.x). Existing assets won’t surface the new check until the cache is refreshed.

Common preflight errors

Error	What it means	Fix
Cost basis is unknown for a transfer-in	A deposit / fork credit / external wallet transfer has no matching purchase event, so the engine can’t establish a cost basis.	Three resolution paths: edit your CSV to add a Purchase row; re-import and reclassify as Income in Step 3 (units enter at FMV with cost basis = receipt-date market price); or exclude the asset.
Insufficient quantity for a disposal	A sale or trade tries to consume more units than the engine has tracked into the pool by that date.	Review the ACB Summary report; the first negative-balance row shows where transactions are missing. Import them, delete the old calculation, and recalculate.
Missing prices for required dates	A disposal date or income receipt date has no market price cached.	Visit the Market Data tab and fetch prices for the asset’s date range. Auto-routing handles dates older than 365 days via CryptoCompare.
No lots in target wallet (US per-wallet only)	Account-by-Account Tracking is enabled and the disposal’s wallet has no acquired lots.	A transfer between your own exchanges wasn’t matched at import. See the US 1099-DA & Account-by-Account Guide.

The full walkthrough — including the heuristic source hint that surfaces when PrivateACB recognizes a known fork or airdrop event (e.g., the post-Merge ETHW airdrop) — lives in the Preflight Errors Guide.

When the preflight check doesn’t run

If you click Calculate and nothing happens, preflight isn’t blocking — something earlier in the chain is. Verify in order: Config Bar selections (jurisdiction, method, asset selected), license status (active or non-expired trial), and that no other calculation is currently running.

---

CSV Import Error Reports

When you upload a CSV file, PrivateACB validates every transaction against required fields, data formats, and value ranges. If the validation process finds errors that prevent import, the system automatically generates a detailed error report so you can fix all the issues in bulk.

What error reports contain

Error reports are CSV files that PrivateACB automatically creates when it finds blocking errors during import validation. These reports contain:

• Your original data - All columns from your CSV preserved exactly as you entered them
• Row numbers - Matching your original file so you can find errors easily
• Error descriptions - Clear explanations of what’s wrong
• Suggested fixes - Specific guidance on how to correct each error

Error reports make it easy to fix multiple errors at once by providing all the information in a format you can view side-by-side with your original CSV file.

---

When Are Error Reports Generated?

Error reports are created automatically during the import validation process only when blocking errors are detected.

Blocking errors are critical issues that prevent import from proceeding, such as:

• Missing required fields (amount, date, asset, etc.)
• Invalid data formats (negative amounts, future dates, malformed timestamps)
• Data type mismatches

Note: Error reports are NOT generated for:

• Warnings - These allow import to proceed with caution
• Duplicates - These are shown in the UI but don’t prevent import
• Successful imports - No errors means no report needed

---

Where Are Error Reports Saved?

Error reports are automatically saved to your PrivateACB logs folder:

C:\Users\[YourUsername]\Documents\PrivateACB\logs\

File Naming Convention

Error reports use this naming pattern:

[original_filename]_ERRORS_[timestamp].csv

Examples:

• coinbase_trades.csv → coinbase_trades_ERRORS_2025-11-11T14-30-00.csv
• my trades (jan 2024).csv → my_trades__jan_2024__ERRORS_2025-11-11T14-30-00.csv

The timestamp ensures you can track multiple validation attempts and see your progress as you fix errors.

---

How to Access Error Reports

During Import Validation

When validation finds errors, the summary panel at the bottom of the preview screen shows:

Summary:
  • 100 transactions selected for import ✅
  • 8 errors must be fixed before import ❌

    Error report saved:
    [📂 Open File]  [Copy Path]

Two ways to access your error report:

1. Open File Button 📂

   • Click to immediately open the error report in your default CSV viewer (usually Excel)
   • Best for: Viewing errors side-by-side with your original CSV

2. Copy Path Button

   • Click to copy the full file path to your clipboard
   • Best for: Sharing the file path, opening in a specific program, or including in notes

Finding Reports Later

If you close the import wizard before viewing the error report:

1. Navigate to Documents/PrivateACB/logs/
2. Look for files ending with _ERRORS_[timestamp].csv
3. Open the most recent file (sorted by timestamp)

Tip: Error reports are kept indefinitely, so you can reference them anytime.

---

Understanding Your Error Report

Report Structure

Error reports contain two sections:

1. Summary Header (First 7-10 lines)

"ERROR REPORT FOR: coinbase_trades.csv"
"Generated: 2025-11-11 14:30:00"
"Total Blocking Errors: 8"
""
"ERROR BREAKDOWN BY TYPE:"
"Missing required fields: 4 errors"
"  - Required field 'amount_base' is missing or empty: 3 errors"
"  - Required field 'asset_symbol' is missing or empty: 1 errors"
"Invalid data types: 4 errors"
"  - Amount cannot be negative: 1 errors"
"  - Price cannot be negative: 1 errors"
"  - Invalid timestamp format: 1 errors"
"  - Transaction timestamp is in the future: 1 errors"
""

This section helps you understand:

• How many errors you need to fix
• What types of errors are most common
• Which specific issues occur most frequently

Use this to prioritize your fixes - if you have 200 missing amounts, fix all amounts first before moving to other errors.

2. Error Details Table (Remaining lines)

Row,Date,Time,Exchange,Type,Asset,Currency,Amount,Price,Fee,Notes,Error,Suggested Fix
1,2024-01-15,10:30:00,Coinbase,buy,BTC,CAD,,50000,2.50,My note,"Required field 'amount_base' is missing or empty","Provide a valid value for amount_base"
2,2024-01-15,11:00:00,Coinbase,sell,ETH,USD,-5,3000,0,Notes here,"Amount cannot be negative","Amount must be a positive number (e.g., 0.5)"
...

Each row shows:

• Row - The line number in your original CSV (use this to find the error)
• All your original columns - Every field from your CSV, preserved exactly
• Error - What’s wrong with this transaction
• Suggested Fix - How to correct the error

---

Common Errors and How to Fix Them

Missing Required Fields

Error Message:

“Required field ‘amount_base’ is missing or empty”

What it means: A critical field is blank or missing in your CSV.

Required fields:

• Date/Time - Transaction timestamp
• Type - Transaction type (buy, sell, mining, etc.)
• Asset - Cryptocurrency symbol (BTC, ETH, etc.)
• Amount - Quantity of crypto

How to fix:

1. Open your original CSV in Excel
2. Go to the row number shown in the error report
3. Fill in the missing field with the correct value
4. Save and re-upload

Example:

Row 5 shows: Amount is empty
Fix: Add the quantity you bought/sold (e.g., 0.5 for half a Bitcoin)

---

Negative Amounts or Prices

Error Message:

“Amount cannot be negative” “Price cannot be negative”

What it means: You entered a negative number (like -5 or -2500) in the Amount or Price field.

Why it’s wrong: PrivateACB uses positive numbers for all amounts. The transaction type (buy vs. sell) determines the direction, not the sign.

How to fix:

1. Find the row with the negative value
2. Change it to a positive number
3. Verify the Type field is correct (buy/sell)

Example:

Wrong: Type=sell, Amount=-5
Right: Type=sell, Amount=5

---

Invalid Timestamp Format

Error Message:

“Invalid timestamp format”

What it means: The date or time is in a format PrivateACB can’t understand.

Accepted formats:

• 2024-01-15T10:30:00 (ISO 8601 - recommended)
• 2024-01-15 10:30:00
• 2024/01/15 10:30:00
• Separate Date and Time columns

Common problems:

• Text instead of dates (e.g., “invalid-date”)
• Wrong date separator (e.g., “2024.01.15”)
• Incomplete dates (e.g., “2024-01”)

How to fix:

1. Open your CSV in Excel
2. Find the row with the invalid date
3. Reformat the date using a standard format
4. Ensure Excel treats it as a date, not text

Tip: If Excel shows the date as text (left-aligned), it won’t validate. Make sure dates are right-aligned (formatted as dates).

---

Future Dates

Error Message:

“Transaction timestamp is in the future”

What it means: The date you entered hasn’t happened yet.

Common causes:

• Typo in year (2025 instead of 2024)
• Wrong date column selected
• Excel auto-format changed the date

How to fix:

1. Find the future date in your CSV
2. Verify the correct date from your exchange records
3. Update to the actual transaction date

---

Missing Quote Currency

Error Message:

“Required field ‘quote_currency’ is missing or empty”

What it means: For buy/sell transactions, you need to specify what currency you used (CAD, USD, EUR, etc.).

How to fix:

1. Check your exchange records for the currency used
2. Add the currency code to the Currency column
3. Use standard codes: CAD, USD, EUR, GBP, etc.

Note: Some transaction types (mining, staking, transfers) don’t require a currency.

---

Step-by-Step: Fixing Errors

1. Open Both Files Side-by-Side

Best practice: Have both files open simultaneously for easy reference.

Option A - Two Excel Windows:

1. Click ”📂 Open File” in PrivateACB to open the error report
2. Open your original CSV in a second Excel window
3. Arrange windows side-by-side (Windows: Win+Left/Right arrows)

Option B - Two Monitors:

1. Error report on one screen
2. Original CSV on the other screen

Option C - Split Screen in Excel:

1. Open both CSVs in Excel
2. Use View → Arrange All → Horizontal

---

2. Fix Errors Systematically

Recommended approach: Fix by error type

Instead of fixing row-by-row, fix all errors of the same type together:

1. Start with the summary header to identify the most common error
2. Fix all instances of that error type
3. Move to the next error type
4. Save after each batch of fixes

Example workflow:

Summary shows: "Missing required field 'amount_base': 200 errors"

1. Sort error report by Error column
2. Find all "amount_base" errors
3. Fix all 200 amounts in your original CSV
4. Save
5. Move to next error type

Why this works:

• Faster than row-by-row (fix 200 at once instead of 1 at a time)
• Reduces mistakes (you’re in the “amount mindset”)
• Easy to track progress (one error type at a time)

---

3. Use the Row Number Column

The Row column in the error report corresponds to the line number in your original CSV.

Important: Excel row numbers start at 1, but your CSV data starts at row 2 (row 1 is headers).

To find the error in Excel:

1. Look at the Row number in error report (e.g., Row 5)
2. In your original CSV, go to Excel row 6 (Row number + 1 for header)
3. Fix the error in that row

Tip: Use Excel’s “Go To” feature (Ctrl+G) to jump directly to a row number.

---

4. Verify Your Fixes

After fixing errors:

1. Save your original CSV (File → Save)
2. Re-upload to PrivateACB
3. Run validation again
4. Check the new error count

Expected results:

• Fewer errors (or zero!)
• New error report generated (if errors remain)
• Import proceeds if no blocking errors

If errors persist:

• Check the new error report
• Verify you saved your fixes
• Ensure you’re uploading the corrected file

---

Tips for Avoiding Errors

Before Uploading

✅ Use exchange export formats when possible

• Coinbase, Kraken, Newton, etc. all have standard export formats
• These are pre-validated and rarely have errors

✅ Check for required fields

• Date/Time
• Transaction Type (buy, sell, mining, etc.)
• Asset Symbol (BTC, ETH, etc.)
• Amount

✅ Use positive numbers only

• All amounts should be positive
• Transaction type determines direction (buy vs. sell)

✅ Verify date formats

• Use ISO format: 2024-01-15T10:30:00
• Or separate Date and Time columns
• Ensure dates are formatted as dates in Excel (right-aligned)

✅ Include currency codes

• CAD, USD, EUR, etc.
• Required for buy/sell transactions

---

During Upload

✅ Review the column mapping step carefully

• Ensure Date maps to Timestamp
• Amount maps to Amount Base
• Type maps to Trade Type
• Asset maps to Asset Symbol

✅ Check the preview table

• Look for obviously wrong data (negative amounts, future dates)
• Verify a few transactions match your exchange records

✅ Read the summary panel

• Error count tells you if there are problems
• Warning count indicates potential issues (can still import)

---

Frequently Asked Questions

Q: Can I delete old error reports?

A: Yes! Error reports are kept indefinitely in the logs folder, but you can safely delete them anytime. They’re reference files to help you fix errors, not required for the application to work.

To clean up:

1. Navigate to Documents/PrivateACB/logs/
2. Delete files ending with _ERRORS_[timestamp].csv
3. Keep recent ones if you’re still fixing errors

---

Q: What if the error report doesn’t open?

A: If clicking ”📂 Open File” doesn’t work:

1. Copy the path using “Copy Path” button
2. Navigate manually to Documents/PrivateACB/logs/
3. Open the file in Excel, Numbers, or any CSV viewer
4. Check file permissions - ensure you have read access

If the file was deleted or moved, it will show an error. Generate a new report by re-uploading your CSV.

---

Q: Why do some rows not show up in the error report?

A: Error reports only include rows with blocking errors. Rows that:

• ✅ Pass validation (no errors)
• ⚠️ Have warnings only (non-blocking)
• 🔄 Are duplicates (shown in UI, not in report)

…will NOT appear in the error report.

To see ALL transactions:

• Use the preview table in the import wizard
• Check the validation summary for counts
• Warnings and duplicates are shown in the UI, not the report

---

Q: Can I edit the error report directly?

A: No! You must fix errors in your original CSV file, not the error report.

Why:

• Error reports are reference guides only
• PrivateACB imports from your original CSV
• Changes to the error report won’t affect the import

Correct workflow:

1. Use error report to identify problems
2. Fix errors in original CSV
3. Save original CSV
4. Re-upload to PrivateACB

---

Q: What if I have hundreds or thousands of errors?

A: Don’t panic! Large error counts usually come from a few systematic issues.

Strategy for large error sets:

1. Check the summary header - Find the most common error type
2. Fix that error type first - Often one fix resolves hundreds of errors
3. Re-validate - See how many errors remain
4. Repeat - Fix next most common error type

Example:

Initial: 500 errors
- 450 missing amounts (forgot to include Amount column)
- 30 negative prices (Excel formatting issue)
- 20 future dates (typo in year)

Fix 1: Add Amount column → 50 errors remain
Fix 2: Make prices positive → 20 errors remain
Fix 3: Fix year typo → 0 errors!

Common systematic issues:

• Wrong column mapping (unmapped columns appear as missing fields)
• Excel auto-formatting (dates, negative numbers)
• Encoding issues (special characters)
• Missing header row

---

Q: Do error reports contain sensitive information?

A: Yes. Error reports contain all the data from your original CSV, including:

• Transaction amounts
• Asset holdings
• Exchange names
• Dates and times
• Notes/memos

Security recommendations:

• Store error reports securely (they’re in your private Documents folder)
• Delete old reports after fixing errors
• Don’t share error reports unless you’re comfortable sharing transaction data
• If sharing for support, redact sensitive fields first

---

Q: What happens if error report generation fails?

A: Error report generation is non-blocking - validation continues even if the report can’t be created.

If generation fails:

• You’ll still see error counts and details in the UI
• The preview table shows all errors inline
• The validation summary panel displays error information
• You can still fix errors and re-upload

Reasons generation might fail:

• Disk space full
• Permissions issue (can’t write to logs folder)
• System error

Workaround:

1. Use the preview table to identify errors
2. Fix errors in your CSV
3. Re-upload and validate again

If error reports consistently fail to generate, check that you have write permissions to Documents/PrivateACB/logs/.

---

Additional Resources

Related Guides

• Preflight Errors Guide — Detailed walkthrough of preflight error types and resolution paths
• Import Flow Guide — Comprehensive guide to importing CSV files (includes column mapping and validation)
• Transaction Types — Full list of supported transaction types
• Classification Review Guide — Step 3 of the import wizard, where you can reclassify rows

Support

If you encounter errors you can’t resolve:

1. Check the error report for suggested fixes
2. Review the validation rules in the CSV Import Guide
3. Verify your CSV matches your exchange’s export format
4. Check exchange documentation for field requirements

---

Summary

Error reports are automatically generated whenever PrivateACB finds blocking errors during CSV import validation. They help you:

✅ Identify errors quickly - Row numbers and clear descriptions ✅ Fix errors efficiently - Suggested fixes for every error ✅ Track progress - Timestamped reports show improvement ✅ Maintain data integrity - All original data preserved

Key points to remember:

1. Error reports auto-generate when blocking errors are found
2. Saved to Documents/PrivateACB/logs/
3. Access via ”📂 Open File” or “Copy Path” buttons
4. Fix errors in your original CSV, not the report
5. Re-upload and validate after fixing
6. Error reports are kept indefinitely (safe to delete old ones)

By using error reports effectively, you can quickly fix validation issues and get your transaction data imported accurately.

---

Last Updated: May 2026 PrivateACB Version: 2.8.1