My PDF or document link is broken after re-uploading a file
When a link to a PDF or document on your site stops working after you have updated the file, it is almost always because the original file was deleted and a new one was uploaded in its place, rather than the file being replaced through the correct method. Understanding how the CMS handles files will help you avoid this in future.
Why this happens
Every file uploaded to the CMS is stored as an asset with its own unique identity and URL. When entries on your site link to a document, they reference that specific asset. If you delete the original asset and upload a new file- even one with the same name- the new file is treated as a completely separate asset with a different identity and URL. Any entries that linked to the original file will still point to the old URL, which no longer exists, resulting in a broken link.
The correct way to update a file
Rather than deleting and re-uploading, Craft CMS has a built-in option to replace a file while keeping its identity and URL intact. To do this, open the asset in the media library by clicking on it, then look for the Replace File option. Select this and upload your new file. The URL and all existing links to that asset across the site will continue to work, now serving the updated file.
Fixing a broken link caused by re-uploading
If the link is already broken because the original file was deleted and a new one uploaded, you will need to re-attach the new asset wherever it is referenced. Open each entry that contained a link to the old file, find the document field, and select the newly uploaded file. Save the entry once updated.
If the document was linked from multiple entries, you will need to update each one individually. If you are unsure where the file was referenced across the site, contact your site administrator who can help locate all instances.
Tip for future updates
Always use Replace File rather than deleting and re-uploading. This is the safest way to update a document and ensures no existing links are broken.
Why this happens
Every file uploaded to the CMS is stored as an asset with its own unique identity and URL. When entries on your site link to a document, they reference that specific asset. If you delete the original asset and upload a new file- even one with the same name- the new file is treated as a completely separate asset with a different identity and URL. Any entries that linked to the original file will still point to the old URL, which no longer exists, resulting in a broken link.
The correct way to update a file
Rather than deleting and re-uploading, Craft CMS has a built-in option to replace a file while keeping its identity and URL intact. To do this, open the asset in the media library by clicking on it, then look for the Replace File option. Select this and upload your new file. The URL and all existing links to that asset across the site will continue to work, now serving the updated file.
Fixing a broken link caused by re-uploading
If the link is already broken because the original file was deleted and a new one uploaded, you will need to re-attach the new asset wherever it is referenced. Open each entry that contained a link to the old file, find the document field, and select the newly uploaded file. Save the entry once updated.
If the document was linked from multiple entries, you will need to update each one individually. If you are unsure where the file was referenced across the site, contact your site administrator who can help locate all instances.
Tip for future updates
Always use Replace File rather than deleting and re-uploading. This is the safest way to update a document and ensures no existing links are broken.