ORGONAUT
Login Signup
Docs
Imports and setup
Fix common import errors

Fix common import errors

When an import run quarantines rows, fix them in the review workflow instead of rerunning blindly.

Where to fix issues

  • Open run review: /imports/{importRun}/review
  • Use resolution filters (pending, reprocessing, failed, fixed, ignored)
  • Open a row, patch fields, and reprocess

The review page is designed for deterministic correction: patch the data, queue reprocessing, and track resolution.

Most common quarantine reasons and fixes

missing_required_field

Typical cause: invalid or blank email.

Fix:

  • provide a valid email
  • confirm no accidental whitespace or malformed addresses

For canonical CSV imports, this still usually means the row is missing its only identity field. For BambooHR or source-aware imports, use the newer identity-specific reasons below when the row can be identified by source record instead of email.

missing_required_identity

The row has neither a valid email nor a complete source identity.

Fix:

  • provide a valid email, or
  • provide both source_hris and source_hris_id, or
  • for BambooHR rows, ensure PersonID / employee_id is present

duplicate_email

Same email appears in multiple rows in one run.

Fix:

  • merge duplicate rows in source CSV
  • keep one canonical row per person identity

duplicate_source_identity

The same source_hris + source_hris_id appears in multiple rows in one run.

Fix:

  • keep one canonical row per source person record
  • remove duplicate source IDs from the source export
  • for BambooHR, confirm PersonID values are unique in the file

identity_conflict

The source identity points to one actor, but the email points to a different actor.

Fix:

  • confirm which actor is correct in the source system
  • correct either the email or the source ID so both identify the same person
  • do not ignore this unless you intentionally want the row excluded

invalid_currency

Currency code not configured for the tenant.

Fix:

  • add/activate currency under /settings/currencies
  • or correct CSV currency code to an active tenant currency

invalid_allocation

allocation_pct outside allowed range.

Fix:

  • use a value between 0 and 300

invalid_fte

fte outside allowed range.

Fix:

  • use a value between 0.01 and 3.00

ambiguous_manager

Manager reference cannot be safely resolved.

Fix:

  • provide consistent manager email
  • if needed, include manager first/last name columns for disambiguation
  • for BambooHR, prefer SupervisorID / manager_employee_id when email is missing or duplicated

Reprocessing workflow

  1. Open quarantined row.
  2. Edit problematic fields.
  3. Save and queue reprocess.
  4. Watch row move through reprocessing to fixed (or failed).

If a row gets stuck in reprocessing, reset it to pending and reprocess again.

If a row is intentionally excluded, mark it ignored.

When to rerun the whole import

Prefer row-level fixes first. Rerun full import when source-level issues are widespread (for example, systemic field mapping problems).

  • Scenario imports: retry path can rebuild a clean scenario copy for rerun.
  • Baseline imports: retry is intentionally stricter to avoid unsafe baseline side effects.

Prevention checklist

Before your next run:

  • enforce one-row-per-identity in source prep
  • ensure each row has either email or a complete source identity
  • standardize department/team naming
  • confirm manager references exist in same file
  • verify currency list in settings