---
# === IDENTITY ===
id: business/erp-integration/oracle-fbdi-common-failures/2026
canonical_question: "What are common Oracle FBDI failures - file format, validation, reference data, UCM permissions?"
aliases:
  - "Oracle FBDI import errors and troubleshooting"
  - "Oracle File-Based Data Import common issues"
  - "FBDI Load Interface File for Import failures"
  - "Oracle ERP Cloud FBDI CSV format errors UCM upload problems"
entity_type: erp_integration
domain: business > erp-integration > oracle-fbdi-common-failures
region: global
jurisdiction: global
temporal_scope: 2024-2026

# === SYSTEM PROFILE ===
systems:
  - name: "Oracle Fusion Cloud ERP"
    vendor: "Oracle"
    version: "25A-25D"
    edition: "Enterprise"
    deployment: cloud
    api_surface: "FBDI (File-Based Data Import)"

# === VERIFICATION ===
last_verified: 2026-03-09
confidence: 0.84
version: 1.0
first_published: 2026-03-09

# === TEMPORAL VALIDITY ===
temporal_validity:
  status: evolving
  last_breaking_change: "25B — new required columns added to several FBDI templates"
  next_review: 2026-09-05
  change_sensitivity: medium

# === CONSTRAINTS ===
constraints:
  - "FBDI files must be ZIP archives containing CSV files — other formats rejected"
  - "CSV file names must match the exact prefix defined in the FBDI template — wrong prefix causes silent rejection"
  - "Load Interface File for Import is all-or-nothing per batch — one bad row rejects entire file"
  - "UCM security groups and accounts control file upload permissions — missing roles cause upload failure"
  - "Field length limits enforced strictly — e.g., description fields truncated or rejected beyond 240 bytes"
  - "Excel FBDI macro has practical limit of ~100,000 rows before becoming unresponsive"

# === SKIP CONDITIONS ===
skip_this_unit_if:
  - condition: "User needs REST API integration, not file-based import"
    use_instead: "business/erp-integration/oracle-rest-api-pagination-pitfalls/2026"
  - condition: "User needs to understand quarterly update impact on FBDI"
    use_instead: "business/erp-integration/oracle-erp-cloud-upgrade-impact-integrations/2026"

# === AGENT HINTS ===
inputs_needed:
  - key: fbdi_module
    question: "Which Oracle ERP module are you importing into?"
    type: choice
    options:
      - "General Ledger (Journal Import)"
      - "Accounts Payable (Invoice Import)"
      - "Accounts Receivable"
      - "Purchasing (PO/Requisition Import)"
      - "Supply Chain (Item Import)"
      - "Fixed Assets"
      - "Projects"
  - key: failure_stage
    question: "At what stage is the FBDI import failing?"
    type: choice
    options:
      - "File upload to UCM"
      - "Load Interface File for Import (ESS job)"
      - "Data import/validation (module-specific job)"
      - "Post-import data quality issues"
  - key: data_volume
    question: "How many records are you importing?"
    type: choice
    options:
      - "< 1,000 records"
      - "1,000-100,000 records"
      - "> 100,000 records"

# === DISTRIBUTION ===
canonical_source: "https://knowledgelib.io/business/erp-integration/oracle-fbdi-common-failures/2026"
suggested_citation: "Source: knowledgelib.io — AI Knowledge Library (verified 2026-03-09)"

# === RELATED UNITS ===
related_kos:
  depends_on: []
  related_to:
    - id: "business/erp-integration/oracle-erp-cloud-upgrade-impact-integrations/2026"
      label: "Quarterly updates can change FBDI template structure"
    - id: "business/erp-integration/oracle-erp-cloud-customization-boundaries/2026"
      label: "Customization boundaries including FBDI"
  solves: []
  alternative_to: []
  often_confused_with:
    - id: "business/erp-integration/oracle-rest-api-pagination-pitfalls/2026"
      label: "REST API integration (different mechanism from file-based import)"

# === SOURCES ===
sources:
  - id: src1
    title: "File-Based Data Import (FBDI) and File Import and Export"
    author: Oracle
    url: https://docs.oracle.com/en/cloud/saas/applications-common/21d/facia/file-based-data-import-fbdi-and-file-import-and-export.html
    type: official_docs
    published: 2024-06-01
    reliability: authoritative
  - id: src2
    title: "Using External Data Integration Services for Oracle ERP Cloud, Release 13"
    author: Oracle
    url: https://www.metaformers.com/wp-content/uploads/2020/04/Using-External-Data-Integration-Services-R13_Oracle.pdf
    type: official_docs
    published: 2023-01-01
    reliability: authoritative
  - id: src3
    title: "Journal Import using File-Based Data Import (FBDI)"
    author: RishOraDev
    url: https://blog.rishoradev.com/2024/03/24/journal-import-using-file-based-data-import-fbdi/
    type: technical_blog
    published: 2024-03-24
    reliability: moderate_high
  - id: src4
    title: "How to gain access to UCM account scm/item/import for FBDI"
    author: Oracle Community
    url: https://community.oracle.com/customerconnect/discussion/672970/how-to-gain-access-to-ucm-account-scm-item-import-for-fbdi
    type: community_resource
    published: 2024-05-10
    reliability: moderate
  - id: src5
    title: "FBDI Import Payables Invoices Load Error"
    author: Oracle Support
    url: https://support.oracle.com/knowledge/Oracle%20Cloud/3057976_1.html
    type: official_docs
    published: 2024-09-01
    reliability: high
  - id: src6
    title: "CSV Generate File error in FBDI Import Item"
    author: Oracle Community
    url: https://community.oracle.com/customerconnect/discussion/745026/csv-generate-file-error-in-fbdi-import-item
    type: community_resource
    published: 2024-07-15
    reliability: moderate
---

# Oracle FBDI Common Failures — File Format, Validation, Reference Data, UCM Permissions

## TL;DR

- **Bottom line**: Oracle FBDI failures fall into 4 categories: file format errors (wrong CSV name/structure), validation failures (bad data values), reference data mismatches (invalid lookups/segments), and UCM permission issues (missing roles to upload files). [src1]
- **Key limit**: Load Interface File for Import is all-or-nothing per batch — one invalid row rejects the entire file. Fix individual row errors, do not attempt partial imports. [src1]
- **Watch out for**: CSV file name prefix must exactly match the FBDI template specification — a wrong prefix causes the file to be silently ignored with no error message. [src2]
- **Best for**: Integration developers and functional consultants troubleshooting Oracle FBDI import failures.
- **Authentication**: UCM file upload requires specific security roles (AttachmentsRead, specific UCM account access) — these are separate from ERP module roles.

## System Profile

Oracle File-Based Data Import (FBDI) is the primary bulk data loading mechanism for Oracle Fusion Cloud ERP. It uses Excel-based templates that generate CSV files, which are compressed into ZIP archives and uploaded to Oracle's Universal Content Management (UCM) server. The ESS job "Load Interface File for Import" then processes these files into Oracle interface tables, followed by module-specific import processes. This card covers the most common failure patterns across all ERP modules (GL, AP, AR, Purchasing, SCM, FA, Projects) and the diagnostic steps to resolve each. [src1, src2]

| Property | Value |
|---|---|
| **Vendor** | Oracle |
| **System** | Oracle Fusion Cloud ERP (25A-25D) |
| **API Surface** | FBDI (File-Based Data Import) |
| **File Format** | CSV in ZIP archive |
| **Upload Target** | UCM (Universal Content Management) |
| **Processing** | ESS Jobs (Load Interface + Module Import) |
| **Editions Covered** | All editions |
| **Deployment** | Cloud |
| **Docs** | [Oracle FBDI Documentation](https://docs.oracle.com/en/cloud/saas/applications-common/21d/facia/file-based-data-import-fbdi-and-file-import-and-export.html) |
| **Status** | GA |

## API Surfaces & Capabilities

| Import Method | Protocol | Best For | Max Records | File Format | Real-time? | Bulk? |
|---|---|---|---|---|---|---|
| FBDI (Excel template) | UCM upload + ESS | Bulk data loads, migrations | ~100K per file (Excel limit) | CSV in ZIP | No | Yes |
| FBDI (programmatic) | REST API + UCM | Automated bulk loads | No hard limit (split files) | CSV in ZIP | No | Yes |
| REST API | HTTPS/JSON | Individual records, real-time | 500 per request | JSON | Yes | No |
| SOAP Web Services | HTTPS/XML | Legacy integrations | Varies | XML | Yes | No |

## Rate Limits & Quotas

### FBDI Processing Limits

| Limit Type | Value | Notes |
|---|---|---|
| Max file size (ZIP) | 250 MB | UCM upload limit |
| Max rows per CSV (Excel macro) | ~100,000 | Excel becomes unresponsive beyond this |
| Max rows per CSV (programmatic) | No hard limit | Split into multiple files for reliability |
| Max concurrent ESS jobs | Configurable per environment | Default varies by customer tier |
| Field description length | 240 bytes | Exceeding causes load error (especially multi-byte characters) |
| CSV file name prefix | Must match template exactly | Wrong prefix = silent rejection |
| ZIP file content | Only CSV files accepted | No XLS, XLSX, or other formats inside ZIP |

[src1, src2]

### Common FBDI Failure Categories

| Category | Frequency | Impact | Typical Resolution Time |
|---|---|---|---|
| File format errors | Very common (40%) | Entire batch rejected | 15-30 minutes |
| Validation failures | Common (30%) | Entire batch or individual rows rejected | 30-60 minutes |
| Reference data mismatches | Common (20%) | Individual rows rejected at import stage | 1-4 hours |
| UCM permission issues | Occasional (10%) | Cannot upload file at all | 30-60 minutes |

## Authentication

| Requirement | Role/Permission | Where Configured | Notes |
|---|---|---|---|
| Upload to UCM | File Import and Export role | Security Console | Required for all FBDI uploads |
| UCM account access | Account-specific role (e.g., scm/item/import) | UCM Admin | Account may not appear in dropdown without this |
| Run ESS jobs | Appropriate module role | Security Console | E.g., General Accountant for GL imports |
| View import results | Same as ESS job role | Security Console | Must be able to view Scheduled Processes |

[src4]

### Authentication Gotchas

- The UCM account dropdown (e.g., scm/item/import) will not show accounts the user lacks permission for — there is no error message, just a missing option. Fix: Assign the appropriate UCM account role via WebLogic Server administration. [src4]
- The user running the Load Interface File for Import ESS job must have both UCM upload permissions AND the module-specific functional role — having only one will cause failure at different stages. [src2]
- Service account (integration user) permissions for FBDI are separate from interactive user permissions — verify both. [src1]

## Constraints

- FBDI files must be ZIP archives containing CSV files — other archive formats (RAR, 7Z) and file formats (XLS, XLSX) inside the ZIP are rejected. [src1]
- CSV file names must match the exact prefix defined in the FBDI template — a wrong prefix causes the file to be silently ignored with a misleading "no valid data files found" error. [src2]
- The Load Interface File for Import process is all-or-nothing per data file — one bad row rejects the entire file, and all rows are deleted from the interface table. [src1]
- Field length limits are enforced strictly — for multi-byte character sets (Japanese, Chinese, Korean), a 240-character field may only hold 80 characters if each character is 3 bytes. [src5]
- The Excel FBDI macro has a practical limit of approximately 100,000 rows before it becomes unresponsive or takes hours to generate the CSV file. [src6]
- UCM virus scanning can reject files — if virus scanning fails or times out, the upload fails with an unclear error. [src2]

## Integration Pattern Decision Tree

```
START — FBDI import failed
├── Where did it fail?
│   ├── File upload to UCM
│   │   ├── "No valid data files found in ZIP"
│   │   │   ├── Check: Is file a valid ZIP? (not renamed XLS)
│   │   │   ├── Check: Does CSV file name match template prefix?
│   │   │   └── Check: Is CSV comma-delimited (not tab/semicolon)?
│   │   ├── UCM account not in dropdown
│   │   │   └── Check: Does user have UCM account role?
│   │   ├── Upload hangs / times out
│   │   │   ├── Check: File size < 250 MB?
│   │   │   └── Check: UCM virus scanner not blocking?
│   │   └── Permission denied
│   │       └── Check: User has File Import and Export role?
│   ├── Load Interface File for Import (ESS job)
│   │   ├── Job status: Error
│   │   │   ├── Check ESS job output log for row-level errors
│   │   │   ├── Common: Field length exceeded (especially multi-byte)
│   │   │   ├── Common: Invalid date format (must be YYYY/MM/DD)
│   │   │   ├── Common: Numeric field contains text
│   │   │   └── Common: Required field is empty
│   │   ├── Job status: Warning
│   │   │   └── Some rows loaded, some rejected — check error report
│   │   └── Job status: Succeeded but 0 rows loaded
│   │       └── Check: CSV prefix mismatch (file silently ignored)
│   ├── Module-specific import (e.g., Journal Import, Invoice Import)
│   │   ├── Reference data validation errors
│   │   │   ├── Invalid GL account segment values
│   │   │   ├── Invalid supplier/customer references
│   │   │   ├── Invalid currency codes
│   │   │   └── Invalid period status (period not open)
│   │   ├── Business rule violations
│   │   │   ├── Duplicate invoice numbers
│   │   │   ├── Cross-validation rules on GL combinations
│   │   │   └── Budget control violations
│   │   └── Data type mismatches
│   │       ├── Amount format (decimal separator)
│   │       └── Date format inconsistencies
│   └── Post-import data quality issues
│       ├── Data loaded but values incorrect
│       │   └── Check: Column order matches template exactly
│       ├── Missing records
│       │   └── Check: Were all rows in CSV? Check row count
│       └── Duplicate records
│           └── Check: Unique key constraints in template
```

## Quick Reference

| Failure Symptom | Root Cause | Fix | Time to Resolve |
|---|---|---|---|
| "No valid data files found in .zip" | CSV file name prefix wrong | Match file name to template specification exactly | 15 min |
| ESS job Error with no details | Field exceeds max length | Check all text fields against length limits | 30 min |
| UCM account not in dropdown | Missing UCM role | Assign UCM account role via admin | 30 min |
| Load succeeds but 0 rows | CSV prefix mismatch | Compare CSV filename to template prefix | 15 min |
| "Structural or formatting anomalies" | BOM characters, wrong encoding | Save CSV as UTF-8 without BOM | 15 min |
| ESS job Warning | Partial load — some rows invalid | Check error report, fix invalid rows | 1 hour |
| Invalid segment value | GL segment not in chart of accounts | Verify all segment values against CoA | 1-4 hours |
| Duplicate record error | Record already exists in target | Check for duplicates before import | 30 min |
| Import succeeds but wrong values | Column order mismatch | Re-download template, verify column order | 1 hour |
| Excel macro not responding | Too many rows (>100K) | Split into multiple files or use programmatic CSV | 30 min |

## Step-by-Step Integration Guide

### 1. Prepare FBDI File Correctly

Download the correct FBDI template from Oracle, populate data, and generate CSV. [src1, src3]

```bash
# Step 1: Download template from Setup and Maintenance
# Navigate: Setup and Maintenance → Search "File Import and Export"
# Select the appropriate FBDI template for your module

# Step 2: Populate template in Excel
# - Use Instructions tab for field specifications
# - Respect column order — do NOT reorder columns
# - Use correct date format: YYYY/MM/DD
# - Respect field length limits

# Step 3: Generate CSV using macro
# Click "Generate CSV File" button in Excel template
# This creates a .csv file in the same directory

# Step 4: Create ZIP archive containing only the CSV file
zip JournalImport.zip JournalImportTemplate.csv
# CRITICAL: CSV filename must match template prefix exactly
```

**Verify**: Open the ZIP file and confirm it contains only the CSV file with the correct prefix name.

### 2. Upload to UCM via REST API

For automated integrations, use the erpintegrations REST API to upload FBDI files. [src2]

```python
# Input:  FBDI ZIP file, Oracle Fusion Cloud credentials
# Output: UCM document ID and ESS job request ID

import requests
import base64

BASE_URL = "https://your-instance.fa.us2.oraclecloud.com"
TOKEN = "YOUR_OAUTH_TOKEN"

# Read and encode the ZIP file
with open("JournalImport.zip", "rb") as f:
    file_content = base64.b64encode(f.read()).decode("utf-8")

# Upload via erpintegrations REST API
payload = {
    "OperationName": "importBulkData",
    "DocumentContent": file_content,
    "ContentType": "zip",
    "FileName": "JournalImport.zip",
    "JobName": "/oracle/apps/ess/financials/generalLedger/programs/common,JournalImportLauncher",
    "ParameterList": "SET_OF_BOOKS_ID,AccountingDate,Source,GroupID"
}

response = requests.post(
    f"{BASE_URL}/fscmRestApi/resources/11.13.18.05/erpintegrations",
    headers={"Authorization": f"Bearer {TOKEN}", "Content-Type": "application/json"},
    json=payload
)

if response.status_code == 201:
    result = response.json()
    print(f"Request ID: {result.get('ReqstId')}")
else:
    print(f"Upload failed: {response.status_code} - {response.text}")
```

**Verify**: Check the response for a valid ReqstId (ESS job request ID). If null, the upload itself failed.

### 3. Monitor ESS Job Status

Poll the ESS job status to determine if the load succeeded or failed. [src2]

```python
# Input:  ESS job request ID from step 2
# Output: Job status (SUCCEEDED, ERROR, WARNING)

import time

def check_ess_status(request_id, token, base_url, max_wait=600):
    """Poll ESS job status until completion or timeout."""
    url = f"{base_url}/fscmRestApi/resources/11.13.18.05/erpintegrations"
    headers = {"Authorization": f"Bearer {token}"}
    params = {"finder": f"ESSJobStatusRF;requestId={request_id}"}

    start = time.time()
    while time.time() - start < max_wait:
        resp = requests.get(url, headers=headers, params=params)
        if resp.status_code == 200:
            items = resp.json().get("items", [])
            if items:
                status = items[0].get("RequestStatus", "UNKNOWN")
                if status in ("SUCCEEDED", "ERROR", "WARNING"):
                    return status, items[0]
        time.sleep(30)  # Poll every 30 seconds
    return "TIMEOUT", None

status, details = check_ess_status(request_id, TOKEN, BASE_URL)
print(f"Job Status: {status}")
if status == "ERROR":
    print("Check job output log for row-level error details")
```

**Verify**: Status should be SUCCEEDED. If ERROR, download the job output log from Scheduled Processes for detailed error messages.

### 4. Retrieve and Parse Error Reports

When an FBDI import fails, download the error report to identify specific row-level issues. [src1]

```python
# Input:  ESS job request ID
# Output: Error report content

def get_error_report(request_id, token, base_url):
    """Download FBDI error report for a failed job."""
    url = f"{base_url}/fscmRestApi/resources/11.13.18.05/erpintegrations"
    headers = {"Authorization": f"Bearer {token}"}
    params = {
        "finder": f"ESSJobStatusRF;requestId={request_id}",
        "fields": "RequestId,RequestStatus,ESSParameters"
    }

    resp = requests.get(url, headers=headers, params=params)
    if resp.status_code == 200:
        items = resp.json().get("items", [])
        if items:
            print(f"Status: {items[0].get('RequestStatus')}")
            # Error details are in the ESS job output log
            # Navigate to: Scheduled Processes → Search by Request ID
            # → Actions → View Output
            return items[0]
    return None

report = get_error_report(request_id, TOKEN, BASE_URL)
```

**Verify**: Error report shows specific row numbers and field-level validation errors.

## Code Examples

### Python: Validate FBDI CSV Before Upload

```python
# Input:  CSV file path, FBDI field specifications
# Output: Validation report with errors per row

import csv
from datetime import datetime

def validate_fbdi_csv(csv_path, field_specs):
    """Pre-validate FBDI CSV to catch errors before upload."""
    errors = []
    with open(csv_path, "r", encoding="utf-8-sig") as f:  # utf-8-sig strips BOM
        reader = csv.reader(f)
        header = next(reader, None)

        for row_num, row in enumerate(reader, start=2):
            for col_idx, spec in enumerate(field_specs):
                if col_idx >= len(row):
                    if spec.get("required"):
                        errors.append(f"Row {row_num}: Missing required field '{spec['name']}'")
                    continue

                value = row[col_idx].strip()

                # Check required fields
                if spec.get("required") and not value:
                    errors.append(f"Row {row_num}: Required field '{spec['name']}' is empty")

                # Check field length (byte-aware for multi-byte chars)
                if value and spec.get("max_bytes"):
                    byte_len = len(value.encode("utf-8"))
                    if byte_len > spec["max_bytes"]:
                        errors.append(
                            f"Row {row_num}: Field '{spec['name']}' is {byte_len} bytes "
                            f"(max {spec['max_bytes']})"
                        )

                # Check date format
                if value and spec.get("type") == "date":
                    try:
                        datetime.strptime(value, "%Y/%m/%d")
                    except ValueError:
                        errors.append(
                            f"Row {row_num}: Field '{spec['name']}' invalid date '{value}' "
                            f"(expected YYYY/MM/DD)"
                        )

                # Check numeric fields
                if value and spec.get("type") == "number":
                    try:
                        float(value.replace(",", ""))
                    except ValueError:
                        errors.append(f"Row {row_num}: Field '{spec['name']}' is not numeric: '{value}'")

    return errors

# Example usage for GL Journal Import
gl_specs = [
    {"name": "LedgerName", "required": True, "max_bytes": 30},
    {"name": "AccountingDate", "required": True, "type": "date"},
    {"name": "EnteredDr", "required": False, "type": "number"},
    {"name": "EnteredCr", "required": False, "type": "number"},
    {"name": "Description", "required": False, "max_bytes": 240},
]

errors = validate_fbdi_csv("JournalImport.csv", gl_specs)
if errors:
    print(f"Found {len(errors)} validation errors:")
    for e in errors:
        print(f"  {e}")
else:
    print("CSV validation passed — safe to upload")
```

### cURL: Upload FBDI File via REST API

```bash
# Input:  FBDI ZIP file, valid OAuth token
# Output: ESS job request ID

# Encode ZIP file to base64
FILE_CONTENT=$(base64 -w0 JournalImport.zip)

# Upload via erpintegrations endpoint
curl -X POST \
  "https://your-instance.fa.us2.oraclecloud.com/fscmRestApi/resources/11.13.18.05/erpintegrations" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"OperationName\": \"importBulkData\",
    \"DocumentContent\": \"$FILE_CONTENT\",
    \"ContentType\": \"zip\",
    \"FileName\": \"JournalImport.zip\",
    \"JobName\": \"/oracle/apps/ess/financials/generalLedger/programs/common,JournalImportLauncher\",
    \"ParameterList\": \"SET_OF_BOOKS_ID,2026/03/01,Manual,BATCH001\"
  }"

# Check job status (replace REQUEST_ID with actual value from response)
curl -X GET \
  "https://your-instance.fa.us2.oraclecloud.com/fscmRestApi/resources/11.13.18.05/erpintegrations?finder=ESSJobStatusRF;requestId=REQUEST_ID" \
  -H "Authorization: Bearer $TOKEN"
```

## Data Mapping

### FBDI File Name Prefix Reference

| Module | FBDI Template | Required CSV Prefix | Common Errors |
|---|---|---|---|
| General Ledger | Journal Import | GlInterface | Using "JournalImport" instead of "GlInterface" |
| Accounts Payable | Invoice Import | ApInvoicesInterface | Using "InvoiceImport" |
| Purchasing | Requisition Import | PorReqInterface | Case sensitivity issues |
| SCM | Item Import | EgpItemInterface | Wrong prefix after template update |
| Fixed Assets | Asset Import | FaAdditionsInterface | Prefix changed between releases |
| Projects | Project Import | PjfProjectsInterface | Missing "Pjf" prefix |

[src1, src2]

### Data Type Gotchas

- Date fields must use YYYY/MM/DD format with forward slashes — Oracle does not accept YYYY-MM-DD (hyphens), MM/DD/YYYY, or DD/MM/YYYY. [src1]
- Amount fields must use period (.) as decimal separator regardless of locale — commas in amounts cause parse errors. [src3]
- Multi-byte characters (Japanese, Chinese, Korean) consume 3 bytes per character in UTF-8 — a 240-byte limit means only 80 CJK characters. [src5]
- Boolean fields expect "Y" or "N" (uppercase) — "Yes", "No", "true", "false", "1", "0" are not accepted. [src1]
- Leading zeros in numeric fields (e.g., account segments "001") may be stripped by Excel — format cells as Text before entering data. [src6]

## Error Handling & Failure Points

### Common Error Codes

| Error | Meaning | Cause | Resolution |
|---|---|---|---|
| "No valid data files found in .zip" | ZIP contains no recognizable CSV | Wrong CSV file name prefix or non-CSV files in ZIP | Verify CSV prefix matches template spec exactly |
| "Load File to Interface ended in error" | Row-level data validation failed | One or more rows have invalid data | Check ESS job output for row-specific errors |
| "Structural or formatting anomalies" | CSV encoding or delimiter issue | BOM characters, wrong encoding, tab-delimited | Re-save as UTF-8 without BOM, comma-delimited |
| JBO-27024 | Attribute not found | Template version mismatch | Re-download template from current release |
| UCM-ACCESS-DENIED | UCM upload permission denied | Missing File Import and Export role | Assign role via Security Console |
| ESS-PARAM-ERR | Invalid ESS job parameters | Wrong parameter order or values | Check parameter list matches job definition |
| FND-SEGMENT-ERR | Invalid segment value | GL segment not in chart of accounts | Verify segment values against active CoA |
| AP-INV-DUP | Duplicate invoice | Invoice number already exists for supplier | Check for duplicates or use different invoice number |

[src1, src2, src5]

### Failure Points in Production

- **CSV file name prefix mismatch**: The most insidious FBDI error — the Load Interface File job completes "successfully" with 0 rows loaded because the CSV file name did not match the expected prefix. No error message is generated. Fix: Always verify CSV file name prefix against the template's Instructions tab. [src2]
- **Excel BOM characters**: When Excel generates CSV files, it may prepend a Byte Order Mark (BOM) that Oracle's parser does not handle correctly. Fix: Open the CSV in a text editor and verify no hidden BOM characters (EF BB BF in hex). Save as UTF-8 without BOM. [src6]
- **Multi-byte field truncation**: Description fields limited to 240 bytes will accept only ~80 Japanese/Chinese characters. Fix: Pre-validate byte length of all text fields using the Python validation script above. [src5]
- **UCM virus scanner timeout**: Large files may trigger the UCM virus scanner to time out, causing an upload failure with no clear error message. Fix: Check UCM server logs, or try splitting the file into smaller chunks. [src2]

## Anti-Patterns

### Wrong: Using Generic File Names for FBDI CSV

```
// ❌ BAD — Using descriptive names instead of template-specified prefix
JournalImport_March2026.csv    ← WRONG — not the template prefix
journal_data.csv               ← WRONG — not the template prefix
data_export.csv                ← WRONG — generic name
```

### Correct: Use Exact Template-Specified CSV File Name Prefix

```
// ✅ GOOD — Using the exact prefix from FBDI template
GlInterface.csv                ← CORRECT for GL Journal Import
ApInvoicesInterface.csv        ← CORRECT for AP Invoice Import
PorReqInterface.csv            ← CORRECT for Purchasing Requisition Import
```

### Wrong: Not Validating Data Before Upload

```python
# ❌ BAD — Upload raw data without pre-validation
# If any row has an error, the entire batch is rejected
# You waste time uploading, processing, and debugging
with open("big_file.zip", "rb") as f:
    upload_to_ucm(f.read())  # 100K rows, one bad date → entire batch fails
```

### Correct: Pre-Validate Every Row Before Upload

```python
# ✅ GOOD — Validate all rows before upload
errors = validate_fbdi_csv("data.csv", field_specs)
if errors:
    print(f"{len(errors)} errors found — fix before upload")
    for e in errors[:10]:  # Show first 10
        print(f"  {e}")
else:
    upload_to_ucm("data.zip")  # Clean data — high confidence of success
```

### Wrong: Editing FBDI Template Column Order

```
// ❌ BAD — Rearranging columns in FBDI template "for readability"
// Oracle's import process reads columns by position, not header name
// Changing order causes data to be loaded into wrong fields silently
```

### Correct: Never Modify Column Order — Use Template As-Is

```
// ✅ GOOD — Keep all columns in original order
// Fill only the columns you need
// Leave unused columns empty (but present)
// If you need a different layout, create a mapping script that outputs
// data in the correct FBDI column order
```

## Common Pitfalls

- **Not checking the Instructions tab in the FBDI template**: The Instructions tab contains critical information about required fields, valid values, field lengths, and the correct CSV file name prefix. Skipping this causes most first-time FBDI errors. Fix: Read the Instructions tab completely before populating data. [src1]
- **Forgetting to re-download templates after quarterly updates**: Oracle may add new required columns or change validation rules between releases. Fix: Re-download all FBDI templates after each quarterly update and compare with your current versions. [src2]
- **Using locale-specific formatting**: Dates in DD/MM/YYYY format, amounts with comma decimal separators, and other locale-specific formats will cause import failures. Fix: Always use YYYY/MM/DD for dates and period (.) for decimals. [src3]
- **Importing into a closed accounting period**: GL journal imports will fail if the accounting period is not open. Fix: Verify the target period is open in the ledger before importing. [src3]
- **Not checking row count after successful import**: A "SUCCEEDED" ESS job may have loaded 0 rows due to CSV prefix mismatch. Fix: Always verify the number of rows loaded matches the expected count. [src2]
- **Large file timeout**: Files approaching the 250 MB UCM limit may timeout during upload. Fix: Split large imports into multiple files of 50 MB or less. [src1]

## Diagnostic Commands

```bash
# Check ESS job status for FBDI import
curl -X GET \
  "https://your-instance.fa.us2.oraclecloud.com/fscmRestApi/resources/11.13.18.05/erpintegrations?finder=ESSJobStatusRF;requestId=YOUR_REQUEST_ID" \
  -H "Authorization: Bearer $TOKEN"

# Download ESS job output (error report)
# Navigate to: Navigator → Tools → Scheduled Processes
# Search by Request ID → Actions → View Output

# Verify CSV file name prefix matches template
# Open the FBDI Excel template → Instructions tab
# Look for "File Name" or "Data File Name" specification

# Check UCM upload permissions
# Navigate to: Navigator → Tools → File Import and Export
# Verify the target UCM account appears in the dropdown

# Validate CSV encoding (should be UTF-8 without BOM)
file your_file.csv
# Expected: "UTF-8 Unicode text" or "ASCII text"
# Bad: "UTF-8 Unicode (with BOM) text"

# Count rows in CSV (should match expected import count)
wc -l your_file.csv
# Subtract 1 for header row
```

## Version History & Compatibility

| Release | Date | Status | FBDI Template Changes | Impact |
|---|---|---|---|---|
| 25D | 2025-11 | Current | New columns in AP/AR templates | Re-download templates required |
| 25C | 2025-08 | Supported | SCM item import template updated | New required fields |
| 25B | 2025-05 | Supported | GL template minor changes | Low impact |
| 25A | 2025-02 | Supported | FA template restructured | High impact for FA imports |
| 24D | 2024-11 | Supported | Multiple template updates | Re-download all templates |

[src1]

### Deprecation Policy

FBDI templates are updated with each quarterly release. Oracle does not formally deprecate old template versions — they simply stop working if Oracle adds required columns or changes validation rules. Always use templates downloaded from the current release. [src2]

## When to Use / When Not to Use

| Use When | Don't Use When | Use Instead |
|---|---|---|
| Troubleshooting FBDI import failures | Need real-time API integration | REST API with oracle-rest-api-pagination-pitfalls card |
| Bulk data migration into Oracle ERP Cloud | Need individual record create/update | REST API endpoints |
| Diagnosing UCM upload permission issues | Need to understand customization options | oracle-erp-cloud-customization-boundaries card |

## Important Caveats

- FBDI templates are release-specific — always re-download from the current Oracle release after each quarterly update.
- The "all-or-nothing" behavior of Load Interface File for Import means one bad row rejects thousands of good rows — pre-validation is not optional, it is essential.
- CSV file name prefix matching is case-sensitive on some Oracle environments — match case exactly.
- UCM permissions are separate from ERP module permissions — a user can have full ERP access but be unable to upload FBDI files.
- Error messages from FBDI are often vague — the detailed errors are in the ESS job output log, not in the initial response.

## Related Units

- [Oracle ERP Cloud Quarterly Update Impact on Integrations](/business/erp-integration/oracle-erp-cloud-upgrade-impact-integrations/2026)
- [Oracle REST API Pagination Pitfalls](/business/erp-integration/oracle-rest-api-pagination-pitfalls/2026)
- [Oracle ERP Cloud Customization Boundaries](/business/erp-integration/oracle-erp-cloud-customization-boundaries/2026)