Firefly III: Import Not Working — Fix

The Problem

You’re trying to import transactions into Firefly III — via CSV, OFX, or bank connection — and the import fails, imports nothing, imports duplicates, or the Data Importer throws errors. Common symptoms:

Updated March 2026: Verified with latest Docker images and configurations.

• Data Importer shows “0 transactions imported” after processing
• CSV import fails with mapping errors or column mismatches
• GoCardless/Nordigen connection times out or returns authentication errors
• Duplicate transactions appearing after every import
• “Could not find a valid account” errors in the import log

The Cause

Firefly III’s import system has several common failure points:

1. Data Importer not connected to Firefly III — the importer is a separate container that needs API access to your Firefly III instance via a Personal Access Token
2. CSV column mapping incorrect — Firefly III expects specific column assignments (date, description, amount, opposing account)
3. Date format mismatch — your bank’s export uses MM/DD/YYYY but the importer expects YYYY-MM-DD
4. Duplicate detection — Firefly III may silently skip transactions it thinks are duplicates based on amount + date + description
5. GoCardless token expired — bank connections expire after 90-180 days depending on the institution

The Fix

Method 1: Data Importer Connection Issues

Verify the Data Importer can reach your Firefly III API:

# Test from inside the Data Importer container
docker exec -it firefly-importer curl -s -o /dev/null -w "%{http_code}" \
  -H "Authorization: Bearer YOUR_PAT_TOKEN" \
  http://firefly:8080/api/v1/about

Expected output: 200. If you get 000 or Connection refused, the containers can’t communicate.

Fix: Ensure both containers are on the same Docker network:

services:
  firefly:
    image: fireflyiii/core:version-6.5.6
    container_name: firefly
    networks:
      - firefly-net
    # ... other config

  firefly-importer:
    image: fireflyiii/data-importer:version-2.2.1
    container_name: firefly-importer
    environment:
      - FIREFLY_III_URL=http://firefly:8080
      - FIREFLY_III_ACCESS_TOKEN=your-personal-access-token
    ports:
      - "8081:8080"
    networks:
      - firefly-net
    restart: unless-stopped

networks:
  firefly-net:

Generate a Personal Access Token: Go to Firefly III → Options (gear icon) → Profile → OAuth → Personal Access Tokens → Create New Token. Copy the full token string into the FIREFLY_III_ACCESS_TOKEN environment variable.

Method 2: CSV Import Mapping Problems

If CSV imports show “0 transactions imported” or mapping errors:

1. Check the date format. Open your CSV in a text editor. If dates look like 03/05/2026, set the date format in the importer to m/d/Y. If they look like 2026-03-05, use Y-m-d.

2. Map the amount column correctly. Some banks export separate debit/credit columns instead of a single amount. In the Data Importer mapping:

   • If your CSV has one Amount column with positive and negative values → map it as “Amount”
   • If your CSV has separate Debit and Credit columns → map them as “Amount (debit column)” and “Amount (credit column)”

3. Set the opposing account. Every transaction needs a source and destination. For expenses, the source is your account and the destination is the merchant. Map the payee/description column to “Opposing account name.”

4. Check for header row. Enable “CSV has headers” in the importer if your first row contains column names, not data.

Common CSV Issue	Fix
”0 transactions imported”	Wrong date format or unmapped amount column
”Could not find account”	The account name in the CSV doesn’t match any Firefly III account
Amounts are wrong	Decimal separator — some banks use comma (1.234,56) vs period (1,234.56)
Everything imports as income	Negative amounts need to be mapped as withdrawal, not deposit

Method 3: Duplicate Detection Too Aggressive

Firefly III skips transactions it considers duplicates. If legitimate transactions are being skipped:

1. Check the duplicate detection settings in the Data Importer configuration:

   • Content-based: matches on amount + description + date
   • Identifier-based: matches on a unique transaction ID from your bank

2. Disable duplicate detection temporarily by setting the import as “no duplicate detection” in the importer configuration, then re-enable after verifying the import.

3. Check for invisible characters in your CSV — some bank exports include BOM markers or trailing whitespace that create false duplicate matches.

Method 4: GoCardless/Nordigen Connection Issues

If your bank connection fails:

Error: Requisition expired
Error: Authentication failed
Error: EUA expired

Fix:

1. Go to the Data Importer → Connections
2. Delete the expired connection
3. Create a new requisition — you’ll be redirected to your bank to re-authorize
4. GoCardless requisitions expire after 90 days (some banks: 180 days). Set a calendar reminder to re-authorize.

If you see “Institution not found,” your bank may have been removed from GoCardless’s supported list. Check the GoCardless institution list for current availability.

Prevention

• Save your CSV import mapping configuration — the Data Importer lets you export your column mapping as JSON. Save it so you don’t reconfigure every time.
• Use consistent account names — create Firefly III accounts with names that exactly match your bank’s export format, or use the “account mapping” feature in the importer.
• Test imports with 5-10 transactions first — don’t import 3 years of history on your first try. Verify the mapping works with a small sample.
• Set GoCardless renewal reminders — 85 days after creating a connection, renew it before it expires.

Related

• How to Self-Host Firefly III with Docker
• Best Self-Hosted Personal Finance Apps
• Actual Budget vs Firefly III
• Self-Hosted Alternatives to Mint