Jira CSV Import: Bulk Issue Creation Without the Headaches

Need to import issues from CSV to Jira? Maybe you're migrating from another tool, setting up a new sprint with a bunch of tickets, or pulling data in from somewhere else. Jira's CSV import can handle it. And here's something that took me way too long to figure out: Summary is the only required field for a basic import.

I'll cover the exact CSV format Jira expects, custom field mapping, and the differences between admin and regular user imports. I'll also get into the error messages that make no sense at first glance (there are a few).

Prerequisites

First, check your permissions. The import method available to you depends on your role.

Jira Cloud Import Methods

Jira Cloud offers two distinct ways to import CSV data:

Need more than 250 issues or want to create new projects during import? You'll need admin access for the External System Import feature. This is annoying but there's no way around it.

Team-Managed Projects

If you can create team-managed spaces, you can use import. But you can't move users between projects during the process.

Preparing Your CSV File

The CSV format is where most imports go wrong. Get this right and you're mostly done.

The Only Required Field

Summary is the only mandatory field. That's it. You can import issues with just a Summary column and Jira will create them in your selected project. I wish more documentation led with this instead of overwhelming you with every possible field.

Fields You'll Probably Want

Summary alone works, but you'll likely want more:

CSV Format Rules

The basics:

• Commas as delimiters (you can change this in Advanced settings)
• Header row required with column names
• Summary column required in the header
• No punctuation in headers - special characters break things
• UTF-8 encoding - the default works for most people
• Consistent commas - don't skip commas for empty values (this trips people up constantly)

Valid CSV Example

Summary, Assignee, Reporter, Issue Type, Description, Priority
"Login page error", bob@example.com, alice@example.com, Bug, "Users cannot log in with SSO", High
"Add dark mode", bob@example.com, alice@example.com, Story, "Implement dark theme toggle", Medium
"Update dependencies", , alice@example.com, Task, , Low

See that third row? Empty Assignee, but the comma's still there. This is the part that catches people off guard.

Invalid CSV Example

Summary, Assignee, Reporter, Issue Type, Description, Priority
"Login page error", bob@example.com, alice@example.com, Bug

This fails. Fewer columns than the header, missing commas for Description and Priority. Jira won't tell you this clearly - you'll just get a vague error.

Special Characters

Commas, line breaks, or quotes in your data? Wrap the field in double quotes:

Summary, Description
"Bug: Login fails", "Click the ""Add"" button and the page crashes"
"Multi-line description", "Step 1: Open app
Step 2: Click login
Step 3: See error"

• Commas in content: Wrap the whole field in double quotes
• Literal double quotes: Use two double quotes ("")
• Line breaks: Wrap in double quotes and they'll be preserved

The Import Process

Here's how to actually get your CSV into Jira Cloud.

Step 1: Access the External System Import

1. Click the Settings gear icon in the top navigation
2. Select System from the menu
3. In the Import and Export section, click External System Import
4. Select CSV from the import options

If you see a "new import experience" interface, click "switch to the old experience" at the top. Honestly, the old experience is better - it has more configuration options and actually lets you import into existing projects.

[Screenshot reference: Jira Settings menu with System highlighted]

Step 2: Upload Your CSV File

1. Click Choose File and select your prepared CSV file
2. (Optional) Check "Use an existing configuration file" if you saved settings from a previous import
3. Expand the Advanced section to configure:
   • File encoding: Default is UTF-8; change if your file uses different encoding
   • CSV delimiter: Default is comma; change to semicolon or tab if needed
4. Click Next

[Screenshot reference: CSV upload dialog with Advanced options expanded]

Step 3: Configure Project Settings

1. Choose your import destination:
   • Select a project: Import all issues into one existing or new project
   • Defined in CSV: Use Project Name and Project Key columns to import to multiple projects
2. Set the Email Suffix for New Users (e.g., @yourcompany.com) if auto-creating user accounts
3. Specify the Date format in import file using Java SimpleDateFormat syntax:
   • yyyy-MM-dd for dates like 2026-02-02
   • dd/MMM/yy for dates like 02/Feb/26
   • yyyy-MM-dd HH:mm:ss for timestamps like 2026-02-02 14:30:00
4. Click Next

[Screenshot reference: Project mapping configuration screen]

Step 4: Map CSV Columns to Jira Fields

This is where you tell Jira what each column means:

1. Check Include in import for each column you want
2. Pick the corresponding Jira field from the dropdown
   • Summary mapping is required - the import fails without it
   • Repeated column headers (like multiple Labels columns) map to multi-value fields
3. Check Map field value if values need transformation (like mapping your custom status names to Jira's)
4. Click Next

[Screenshot reference: Field mapping interface showing column-to-field assignments]

Step 5: Configure Value Mappings

If you checked "Map field value" for any columns, now you map the actual values.

For each value in your CSV, select or enter what it should become in Jira. Priority and Resolution fields let you click Add new... to create values. Status fields don't - you have to map to existing workflow statuses, which is frustrating if your CSV has custom statuses.

For unresolved issues, change Resolution from "Unresolved" to "Import as blank".

Click Begin Import when you're done.

[Screenshot reference: Value mapping screen showing status and priority mappings]

Step 6: Monitor and Save

Watch the progress bar. When it finishes, click Download detailed log if you see warnings or errors.

Save the configuration file. Seriously. It stores your field and value mappings, so the next import with a similar CSV structure takes about two minutes instead of twenty.

[Screenshot reference: Import progress screen with log download option]

Custom Field Mapping

Jira has some special syntax for complex field types. Here's what you need to know.

Multi-Select Fields

Use repeated column headers to import multiple values into a single multi-select field:

Summary, Labels, Labels, Labels
"Feature request", frontend, ui, high-priority

This creates one issue with three labels: frontend, ui, and high-priority.

Cascading Select Fields

Use arrows (->) for parent-child values:

Summary, Department
"New hire setup", Engineering -> Frontend
"Budget request", Finance -> Operations

Value before the arrow = parent. Value after = child.

Date and Time Fields

Dates use Java SimpleDateFormat syntax (yes, really). Common patterns:

Set your date format in Step 3.

Time Tracking Fields

Time values are in seconds (not minutes, not hours):

Summary, Original Estimate, Time Spent
"Code review", 7200, 3600

7200 seconds = 2 hours. 3600 seconds = 1 hour. Keep a calculator handy.

Worklog Entries

You can import time tracking history with dates, authors, and comments:

Summary, Worklog
"Basic worklog", 3600
"With date and author", 2026-01-15 12:30:00;user@example.com;3600
"With comment", Code review session;2026-01-15 12:30:00;user@example.com;7200

Format: comment;createdDate;author;timeSpentSeconds

Comments

Comments can include author and timestamp:

Summary, Comment
"Issue with comments", "2026-01-15 10:00:00;reviewer@example.com;Looks good, approved for deployment"

Format: createdDate;Creator;commentBody

Parent-Child Relationships

You can import Epics with their Stories and Sub-tasks in one CSV. This takes some setup but saves a lot of time.

Required Columns for Hierarchy

The Catch

Parent issues must appear before children in the CSV. Epics before their Stories, Stories before their Sub-tasks. If you get this wrong, the import will create orphaned issues.

Also: IDs must be unique within your CSV, and Parent references use your CSV's Work item ID - not Jira issue keys.

Hierarchy Import Example

Issue Type, Summary, Work item ID, Parent
Epic, "Q1 Product Launch", 1,
Story, "Design landing page", 2, 1
Story, "Implement checkout flow", 3, 1
Sub-task, "Create wireframes", 4, 2
Sub-task, "Build responsive layout", 5, 2
Task, "Write documentation", 6, 1

This creates:

• Q1 Product Launch (Epic)
  • Design landing page (Story, child of Epic)
    • Create wireframes (Sub-task, child of Story)
    • Build responsive layout (Sub-task, child of Story)
  • Implement checkout flow (Story, child of Epic)
  • Write documentation (Task, child of Epic)

Importing to Multiple Projects

If your issues need to go to different Jira projects, include both Project Name and Project Key columns:

Issue Type, Summary, Project Name, Project Key
Bug, "Login timeout", Web Application, WEBAPP
Bug, "API rate limit", Backend Services, BACKEND
Story, "Mobile redesign", Mobile App, MOBILE

Both are required when using "Defined in CSV" in Step 3. Just having one doesn't work.

Updating Existing Issues

CSV import isn't just for new issues - you can update existing ones too.

Add Issue Key Column

Include Issue Key with existing Jira keys:

Issue Key, Summary, Priority, Labels
PROJ-101, Updated summary text, High, urgent
PROJ-102, , Medium, reviewed

Row 1 updates PROJ-101's summary, priority, and adds a label. Row 2 updates PROJ-102's priority and label - the empty Summary means no change.

Clearing Fields

Use <<!clear!>> to remove existing values:

Issue Key, Labels, Assignee
PROJ-103, <<!clear!>>,
PROJ-104, , <<!clear!>>

Row 1 removes all labels from PROJ-103. Row 2 removes the assignee from PROJ-104.

Common Errors (And How to Fix Them)

Invalid Date Format

Message: Invalid date format. Please enter the date in the format "MMM/dd/yy"

This is one of the most frustrating errors because the actual cause varies. Your dates might not match what you specified in Step 3. Or dates are inconsistent within the file. Or AM/PM times use 0 instead of 12. Or you used dashes when Jira expected slashes.

What to do:

• Check Jira's date format in Settings > System > Look and Feel > Complete Date/Time Format
• Make sure ALL dates in your CSV use identical formatting
• Open the CSV in a plain text editor (not Excel) to see what's actually there - Excel displays dates differently than it stores them

Priority Not in Project Schema

Message: Priority [ Medium ] is not in the project [ TEST ] Priority Schema

Your CSV has a priority value that doesn't exist in that project. You can either add the priority to Jira's scheme, change your CSV to use existing values, or map the values in Step 5.

Status Cannot Be Created

Your CSV has status values that don't exist in Jira. Here's the annoying part: unlike Priority and Resolution, you can't create new statuses during import.

Either map your CSV statuses to existing workflow statuses in Step 5, or modify your project's workflow before importing.

Summary Field is Required

Message: Summary field is required

Check that your CSV has a column header named exactly "Summary" - capitalization matters. Also verify you mapped a column to Summary in Step 4. If it looks right, open the file in a text editor and check for invisible characters or encoding issues in the header row.

Cannot Import to Existing Project

The new import experience only lets you create new projects. This feels like a step backward to me.

Fix: Click "switch to the old experience" at the top of the import screen. The old experience lets you import into existing projects.

User Not Found

Use email addresses instead of usernames for Assignee and Reporter fields. Make sure the users actually exist in your Jira instance. Admins can enable auto-creation with the email suffix setting.

One gotcha: Watchers must already exist. Auto-creation doesn't work for that field.

Large Imports

Limits

Tips

Split large files into batches of 1,500 or fewer. Test with 10-20 issues first to verify your mapping works. Run large imports during off-peak hours if you can - they do slow things down for other users.

Save your configuration file. Keep a backup of your original CSV.

Cloud vs Data Center

Using Data Center instead of Cloud? Here are the differences:

Jira Server reached end of support in February 2024. If you're still on Server, you're probably already planning a migration.

Character Limits

Quick reference for field limits:

Data exceeding these limits gets trimmed silently. You won't see a warning - it just cuts off.

Attachments

You can import file attachments via URLs:

Summary, Attachment
"Bug report", "https://example.com/screenshots/error.png"
"With metadata", "2026-01-15 10:00:00;account-id;requirements.pdf;https://files.example.com/requirements.pdf"

URLs must be HTTP or HTTPS - file:// paths don't work. Files need to be accessible from Jira Cloud's servers, and large attachments will slow things down.

Wrapping Up

The key things: Summary is your only required field. Use the old import experience for full features. Match date formats exactly. Test with small batches before going big.

Jira's CSV import works fine for admin-driven migrations and bulk operations. But if you need end users to upload their own CSV data without admin access, or you're building imports into your own application, the built-in tools get limiting fast.

ImportCSV provides embeddable CSV import components with validation, transformation, and mapping built in. No complex wizards for users to navigate. Worth looking at if you need more control than Jira gives you out of the box.