In Jira, an attachment is any file you upload directly to an issue: a screenshot, a log file, a PDF, a spreadsheet. It's called an issue in Jira's interface, or a work item in Jira's newer terminology, though most people still just call it a ticket. Whatever you call it, adding a file to one takes seconds: drag it in, paste it, or click the paperclip icon.
This guide covers every way to add an attachment in Jira Cloud and Jira Data Center, from basic drag-and-drop to the REST API, plus the size limits, permissions, and troubleshooting steps that actually stop people mid-upload. It also covers the one thing native Jira still can't do: edit an attachment without downloading it, editing it, and re-uploading it as a brand new file.
Key takeaways:
Two things need to be true before you can add a file to a Jira issue: you need the Create Attachments permission on that project, and attachments need to be enabled at the instance level (they're on by default).
Admins manage both permissions under Project Settings > Permissions or a global permission scheme and attachment settings under Settings > System > Advanced > Attachments. If your upload fails silently, a missing permission is the most common reason, worth checking before you assume the file itself is the problem. One easy-to-miss cause specifically for attaching during issue creation: if the Attachment field is hidden in that issue type's field configuration, the option simply won't appear, no error, just no attach option.
Deleting works the same way in reverse. Delete Own Attachments lets you remove files you personally uploaded; Delete All Attachments lets you remove anyone's. ikuTeam Office for Jira & JSM, covered later in this guide, ties its own editing permissions to these same two settings, so it's worth understanding them regardless of which tools you end up using.
File size is where most confusion starts. On Jira Cloud, the default limit is 1 GB per file, and admins can raise that to 2 GB. On Jira Data Center, the default is much smaller: 10 MB, adjustable through the jira-config.properties file, up to the same 2 GB ceiling. If you're troubleshooting a failed upload and aren't sure which environment you're on, this is the first thing to check.
Storage adds a second ceiling on Cloud specifically, separate from the per-file limit. Free plans get 2 GB of file storage per app, Standard plans get 250 GB, and Premium plans are unlimited. A single 1.9 GB video might clear the file-size limit and still blow through a Free plan's entire storage quota in one upload.
File names matter too. Jira rejects characters like \, /, ", %, :, $, ?, and *, and admins can block specific extensions (.exe and .bat are common) for security. If a small file still won't upload, check the filename for stray punctuation before you check anything else.
Jira doesn't limit attachments to a fixed list of approved formats, images, documents, code, archives, audio, and video all upload without any special configuration. Here's what covers the vast majority of real-world attachments:
|
Category |
Formats |
Typical use |
|
Images |
.jpg, .png, .gif, .svg, .bmp |
Bug screenshots, design mockups |
|
Documents |
.pdf, .docx, .xlsx, .pptx, .odt, .ods, .odp |
Specs, reports, roadmaps |
|
Text and code |
.txt, .log, .java, .js, .py, .rb, .sql |
Stack traces, config files, queries |
|
Archives |
.zip, .tar, .gz, .jar |
Bundled logs, build artifacts |
|
Audio |
.mp3, .wav, .aac |
Call recordings, voice notes |
|
Video |
.mp4, .mov, .avi |
Screen recordings, demos |
Images and many document formats get a thumbnail preview right in the issue. ZIP and JAR files can get special handling too: admins can turn on ZIP Support under the same attachment settings covered above, which lets anyone preview the contents of a ZIP file and download every attachment on an issue as a single ZIP, without digging through the archive's folder structure by hand.
For anything genuinely large, multi-gigabyte recordings, database dumps, container images, don't fight the size limit. Host the file somewhere built for it and link to it from the issue instead. That's a cleaner instance and a faster page load than a 1.9 GB video sitting in an attachments panel.
There are four ways to get a file onto a Jira issue, and which one you reach for usually depends on what you're doing at the moment.
Drag and drop. Open the issue, drag one or more files from your computer onto the description or comment area, and drop them. A highlighted zone appears while you're dragging, and each file uploads with its own progress indicator. This is the fastest method when the file is already open in a folder on your screen.
The Attach button. Click the paperclip icon, or the "+" icon depending on your Jira version and screen size (on narrower views it can be tucked under "More"). Browse your filesystem, select one or more files, and confirm. This is the most reliable method when drag-and-drop isn't practical, on a touch device, for example.
Paste from clipboard. Capture a screenshot with your OS tools (Windows Snipping Tool or Win+Shift+S, macOS Shift+Cmd+4, or your Linux distribution's equivalent), click into the issue's description or comment field, and press Ctrl+V or Cmd+V. Jira turns the clipboard image into an inline PNG attachment automatically, no save-to-disk step required. Some browsers ask for clipboard permission the first time; allow it, or the paste silently fails.
During issue creation. In the Create dialog, drag files into the attachment area or use the Attach Files control before you submit. Attaching at creation time ties the file to the issue from the moment it exists, rather than adding it as an afterthought in a follow-up comment.
However you attach a file, it lands in the issue's Attachments section immediately, visible to anyone with access to the issue.
Attaching a file while writing a comment works exactly like attaching one to the issue itself: use the paperclip icon or drag the file into the comment editor. The difference is context. A comment attachment stays visibly tied to the specific update it belongs to, which matters on an issue with a long history, a support engineer attaching a packet capture to one particular follow-up, for instance, rather than dropping it into the general pile.
Every file attached through a comment also shows up in the issue's main Attachments section, so nothing gets hidden by attaching it this way. You're choosing where it's easiest to find later, not choosing between visibility and privacy.
Customers using a Jira Service Management request portal attach files the same way they'd attach one to an email: an "Add attachment" link or a drag-and-drop area right in the request form. Agents control two things worth knowing about: whether customers can attach files at all, and the size limit that applies at the portal level, which can differ from the limit set for internal issues.
Visibility isn't a separate flag on the file itself, it follows the comment it's attached to. Post it on an internal comment and only agents see it; post it on a public comment and the customer sees it too. That's worth knowing before attaching a screenshot with sensitive account details in a reply.
Editing one of those attachments runs into the same limitation this guide covers in full further down: native Jira has no way to edit a file in place, on the portal or off it. ikuTeam Office for Jira & JSM is currently the only Marketplace app built to close that gap for JSM tickets specifically. Its Advanced tier lets an agent open a customer's attached spreadsheet or PDF and edit it inline, right on the request, instead of downloading it, editing it locally, and re-uploading a new version before replying.
If you're evaluating apps specifically for JSM and ITSM workflows beyond attachments, the Best Apps for Jira Service Management and ITSM Teams section of our Jira apps guide covers SLA reporting, monitoring integrations, and customer-facing tools.
Once files start piling up on an issue, the Attachments panel is where you handle all of it. Each entry shows filename, size, uploader, and upload date, and you can sort by name, date, or type depending on your Jira version.
Previewing. Click a filename or thumbnail to preview images and most document formats without leaving the issue. Next/previous controls let you flip through several screenshots in a row, handy during a design review or a bug triage session with a handful of related images.
Downloading, exporting, and backing up. Open an attachment's context menu and choose Download to save it locally, or use the bulk ZIP download covered above for everything on the issue at once. Beyond a single issue, you can export issues along with their attachments and comments through Jira's export tools, useful for compliance archiving or migrating data out of a project.
Deleting. Click the delete icon on any attachment you have permission to remove (see the permissions section above). Two limits matter here: an issue can hold up to 2,000 attachments total, and once it passes 150, Jira switches from a preview grid to a plain list to keep the page usable. If you're regularly hitting either number, that's usually a sign attachments are being used as long-term file storage rather than issue context, and it's worth moving that content somewhere purpose-built instead.
One habit worth building: don't delete a file referenced in an old comment or an audit trail unless you're certain nobody needs it. Once it's gone, the comment pointing at it is just a dead reference.
If you're automating uploads, from a CI/CD pipeline, a monitoring tool, or a script, you'll hit the same endpoint regardless of language:
POST /rest/api/3/issue/{issueIdOrKey}/attachmentsOn Server or Data Center, use /rest/api/2/... instead of /rest/api/3/....
Three things trip people up on this endpoint specifically. First, it requires the X-Atlassian-Token: no-check header; without it, Jira's CSRF protection blocks the request outright. Second, the request body has to be multipart/form-data, and the field holding the file must be named exactly file. Third, whatever account is making the request needs Browse Projects and Create Attachments permission on the target project, the same as a human user would.
cURL:
bash
curl -X POST 'https://your-domain.atlassian.net/rest/api/3/issue/TEST-123/attachments' \
-u 'user@example.com:api_token' \
-H 'X-Atlassian-Token: no-check' \
-F 'file=@"path/to/myfile.txt"'
Python (using requests):
python
import requests
from requests.auth import HTTPBasicAuth
url = "https://your-domain.atlassian.net/rest/api/3/issue/TEST-123/attachments"
auth = HTTPBasicAuth("user@example.com", "api_token")
headers = {"X-Atlassian-Token": "no-check"}
files = {"file": open("path/to/myfile.txt", "rb")}
response = requests.post(url, headers=headers, auth=auth, files=files)
print(response.status_code, response.json())
Node.js (using axios and form-data):
javascript
const axios = require('axios');
const FormData = require('form-data');
const fs = require('fs');
const form = new FormData();
form.append('file', fs.createReadStream('path/to/myfile.txt'));
axios.post(
'https://your-domain.atlassian.net/rest/api/3/issue/TEST-123/attachments',
form,
{
auth: { username: 'user@example.com', password: 'api_token' },
headers: { ...form.getHeaders(), 'X-Atlassian-Token': 'no-check' }
}
).then(res => console.log(res.status, res.data));
Java (using OkHttp):
java
OkHttpClient client = new OkHttpClient();
RequestBody fileBody = RequestBody.create(new File("path/to/myfile.txt"), MediaType.parse("application/octet-stream"));
RequestBody body = new MultipartBody.Builder()
.setType(MultipartBody.FORM)
.addFormDataPart("file", "myfile.txt", fileBody)
.build();
Request request = new Request.Builder()
.url("https://your-domain.atlassian.net/rest/api/3/issue/TEST-123/attachments")
.header("Authorization", Credentials.basic("user@example.com", "api_token"))
.header("X-Atlassian-Token", "no-check")
.post(body)
.build();
Response response = client.newCall(request).execute();
Using Postman: set the request to POST, paste in the endpoint with your issue key, add Basic Auth with your email and API token, add the X-Atlassian-Token: no-check header, and under Body choose form-data with a key named file set to type File.
A successful call returns HTTP 200 and a JSON array, one entry per uploaded file, with its id, filename, size, MIME type, author, creation date, and both a content URL and a thumbnail URL. That id is what you'd reference to link the attachment elsewhere, a Jenkins pipeline posting test results back to the triggering issue, for example, or a script pulling recent logs onto an incident.
Everything above assumes you're adding a new file. Editing an existing one is a different problem, and native Jira genuinely has no answer for it. Attachments are immutable: once a file is uploaded, there's no edit button, no "save changes back to the original." Changing a single cell in an attached spreadsheet means downloading it, opening it in Excel, editing the cell, saving it, going back to Jira, deleting the old attachment, and uploading the new one. Ten minutes, every time, for a change that should take seconds.
Do that a few times on the same document and you end up with budget_v1.xlsx, budget_v2.xlsx, and budget_v2_FINAL.xlsx sitting in the same issue, with nothing in Jira itself telling you which one is actually current. Worse, that stale file doesn't announce itself. Whoever opens it next has no way of knowing it's out of date, so decisions get made on outdated information without anyone realizing it.
This isn't a minor complaint. Atlassian's own public feature tracker has an open request for exactly this, "Inline Editing Attachments, SharePoint-like functionality," filed in December 2013. As of today, it's still marked "Gathering Interest," not built, with 30 votes and 23 watchers still active on it. Twelve years is a long time for a request to sit open on your own product, and it's about as honest a signal as you'll find that this gap is real rather than a talking point.
ikuTeam Office for Jira & JSM closes it. Click an attachment, and it opens for editing right inside the Jira issue itself, no new tab, no download. Multiple people can edit the same document at once, and saving writes back to the exact same attachment instead of creating a new one, with version history tracked automatically so it's clear what changed and when, without a single _FINAL in sight. ikuTeam puts the time savings at 5 to 10 times faster editing per attachment, which adds up fast across a team that's routinely updating spreadsheets, specs, and reports attached to Jira issues. The Standard tier covers attaching, previewing, and editing Word, Excel, and PowerPoint files, plus creating new Office documents directly from an issue. Advanced adds PDF editing and annotation, along with support for Jira Service Management.
There's a cost angle too, not just a time one. On top of a Jira license, many teams end up paying for Microsoft licenses as well, just so someone can open and edit a file that's already sitting in their own workspace. Editing natively inside Jira removes that requirement entirely, one fewer license to buy, renew, and manage.
Permissions follow Jira's own rules rather than a separate system: someone with Delete Own Attachments can only edit files they uploaded, while Delete All Attachments lets them edit anything on the issue, the same permissions covered earlier in this guide, just extended to editing instead of only deleting. The app is built on Atlassian Forge, meaning it runs inside Atlassian's own infrastructure rather than a third-party server, and it supports GDPR and CCPA compliance since it never stores a copy of the file anywhere outside Jira.
It isn't a replacement for the REST API or automation rules covered above. It solves a narrower, specific problem: the one where a human needs to update a document that's already attached, without turning the issue into a graveyard of file versions.
This is a different kind of automation from the REST API uploads covered earlier. Pushing a file in from a CI/CD pipeline or a script is initiated by your own system, so it doesn't need a trigger. This section is about the reverse: getting Jira itself to notice an attachment and react to it.
Attachments are one of the harder things to automate natively in Jira. There's no dedicated "attachment added" trigger, so reacting to a new file usually means pairing a Field Updated trigger on the Attachments field with a separate rule on Comment Added that checks for attachments through a condition, since a file added inside a comment doesn't register as a field update. Requiring an attachment before a transition works through Jira's built-in Field Required validator, but only for attachments added on the transition screen itself; one already sitting on the issue from earlier doesn't satisfy it.
That's a different question from automating cloud storage, which is more capable. Apps like ikuTeam Files for Jira, SharePoint Connector for Jira, and Google Drive Connector for Jira add their own actions, Create Folder, Connect a Folder, Upload Attachments to Folder, directly into Jira's native rule builder. Those actions manage the cloud folders and files connected to an issue, not the native Jira attachments covered in this guide. For that side of things, and for the fuller picture of Jira's automation rule builder generally, see Jira Automation: The Ultimate Guide for Smarter Workflows.
Screenshots make up a large share of real-world Jira attachments, especially for UI bugs and incident timelines, and the clipboard method covered earlier is the fastest way to handle them: capture with your OS tool, click into the issue or comment, paste, done.
Two habits make screenshots more useful later. Name them with something searchable if you're saving locally before upload, a pattern like 2026-07-14-login-error-chrome.png ages a lot better than Screenshot 2026-07-14 at 3.42.11 PM.png once a project has hundreds of them. And blur or crop out anything sensitive, credentials, personal data, internal URLs, before it becomes a permanent attachment on an issue that support, an auditor, or a future new hire might open.
Snagit doesn't post to Jira out of the box, but its recents tray makes drag-and-drop nearly instant, and community-built output plugins exist that push a capture straight into a Jira issue over the same REST API covered above. Any tool that can perform a multipart upload to that endpoint works, regardless of what the tool calls itself.
|
Symptom |
Likely cause |
Fix |
|
Upload fails with no error message |
Missing Create Attachments permission |
Ask your Jira admin to check your project's permission scheme |
|
"Could not attach file, missing token" |
A CSRF token issue, common on some browser or proxy setups |
Refresh the page and retry; clear cookies for the site or try a different browser if it persists |
|
Small file still won't upload |
Special characters in the filename (\, /, ", %, :, $, ?, *) |
Rename using only letters, numbers, hyphens, and underscores |
|
File type rejected |
Extension is on the instance's blocklist (.exe and .bat are common) |
Zip the file first, or ask an admin to review the allowlist |
|
"Unknown server error" (413 or 500) |
File exceeds the configured size limit |
Check the Cloud (1 to 2 GB) or Data Center (10 MB default) limit covered earlier, and confirm with your admin if it's been raised |
|
Drag-and-drop does nothing |
A browser extension or ad blocker interfering, or you're not in an editable field |
Try the paperclip button instead, or test in an incognito window |
If none of these match what you're seeing, a quick test isolates the cause fast: try uploading a plain .txt file. If that works, the problem is specific to your original file, its name, type, or size. If it doesn't, the problem is permissions, instance settings, or your network, not the file at all.
How do I add an attachment to a Jira ticket? Open the issue, and either drag a file onto it, click the paperclip (Attach) icon and browse to it, or paste a screenshot directly from your clipboard with Ctrl+V or Cmd+V. All three add the file to the issue's Attachments section immediately.
What is the maximum file size for a Jira attachment? On Jira Cloud, the default is 1 GB per file, and an admin can raise it to 2 GB. On Jira Data Center, the default is 10 MB, adjustable up to the same 2 GB ceiling through jira-config.properties.
How many attachments can one Jira issue have? Up to 2,000. Past 150 attachments, Jira switches from a preview grid to a plain list view to keep the page responsive.
Can I edit a file I already attached to Jira? Not natively. Jira treats every attachment as a separate, unchangeable file, so the standard workaround is download, edit, and re-upload as a new attachment. ikuTeam Office for Jira & JSM removes that workaround by editing the attachment inline and saving back to the same file.
How do I add an attachment to Jira using the REST API? Send a multipart/form-data POST request to /rest/api/3/issue/{issueIdOrKey}/attachments with the file in a field named file and an X-Atlassian-Token: no-check header. Works the same whether you're calling it from cURL, Python, Node, Java, or Postman.
Why is my Jira attachment upload failing even though the file is small? Usually one of four things: a missing Create Attachments permission, special characters in the filename, a blocked file extension, or a temporary network issue. Testing with a plain .txt file quickly tells you whether the problem is the file itself or something else.
Does Jira Service Management handle attachments differently? Customers attach files through the request portal the same way they would through email, and agents control whether attachments are allowed at the portal level and whether each one is visible to the customer or kept internal.
Are Jira attachments backed up and secure? On Jira Cloud, Atlassian handles encryption at rest and in transit as part of its own infrastructure. On Data Center, backup and security are your organization's responsibility, so confirm your backup schedule with whoever administers your instance.
Can Jira search the text inside an attached file? Not by default. Jira's search indexes issue fields, not the contents of arbitrary attachments. If full-text search across documents matters to your team, that typically means pairing Jira with a connected knowledge tool rather than relying on native search.