How to fix broken links and redirects

Last updated on January 24, 2023 at 3:05 pm
It's important to address broken links as soon as you find them. Learn how to find and fix a broken link.
This article is for:
All products

In this guide

↓ Why do broken links matter?

↓ How do I know I have a broken link?

↓ Repairing broken links

↓ Top causes of broken links

Why do broken links matter?

Site visitors who click on a broken link end up with a frustrating, dead-end experience. This may prevent Veterans from accessing the services they need. It can also make things especially difficult for people using assistive technology.

Broken links can also cause technical problems with the publishing process. That's why the CMS has tools in place to check content for broken links and help you fix them.

How do I know I have a broken link?

Screenshot showing the expanded broken link alert.

The CMS checks for broken links each time you save content. If it finds a broken link, you'll see an alert at the top of the content's View or Edit screen.

  1. Click the arrow to expand the alert. The expanded alert will provide more information about what the link is and why it broke.
  2. Examine the text in brackets. This is the link text. Check to make sure you've used full words and phrases.
  3. Examine the link next to the text. This is the URL. Click the link to see if it works. If it doesn't work, check for typos.
  4. If you can't determine the problem based on the information in the link report, check out top causes of broken links.

Repairing broken links

  1. Once you know which piece of text has the broken link, go to the Edit tab for your content.
  2. Locate the text on the edit screen. 
  3. If the text is in a rich text field, highlight it and click the link button to edit the URL.
  4. Remove or edit the URL.
  5. Save the content.
  6. Check to make sure the link is no longer broken and the alert at the top of the content no longer displays.

Top causes of broken links

Linking to an archived page

When you see a number of broken links appear in various pieces of content at the same time, it's usually because you recently archived a page. When you archive a piece of content it will cause links to break in all the other pages that link to it.

What the alert looks like

The link checker shows a number of broken links in your content all at once.

How to fix it

  • Before archiving, check other content that is likely to have a link to that page. You'll need to update or remove the links to the page you're about to archive.
  • If you've already archived a page, check related pages for broken links and repair them.

Copying a link from Outlook

If the link contains a segment with “safelinks.protection.outlook”, it’s likely you copied the link from an email. Outlook automatically rewrites links, adding the safelink segment which is unneeded in CMS and causes the break.

What the alert looks like

1 broken link found
Repair the following broken link to avoid errors:
[MTA Planner] https://gcc02.safelinks.protection.outlook.com/?url=https%3A%2F%2Fnew.m…...

How to fix it

  • Click on the link in the alert.
  • If the page opens to a valid webpage, replace the corrupt link with a new one copied from the browser.
  • Double check the top of your page after saving to make sure the broken link alert is no longer displayed. 
  • Remember, if these broken links appear on published pages, you'll need to save the changes you made to fix them as Published.

Linking to a URL that is being redirected

Sometimes other sites will direct a link to an old URL to a new one they'd like people to use instead. The CMS flags when you've linked to a page that is being redirected. It's better to use the URL for the link's new destination in case the old URL gets removed in the future.

What the alert looks like

1 redirected link found
Please update the following URLs to prevent the possibility of broken links in the future.
Update [Veteran's Whole Health Care] https://youtu.be/Rq1UcOPrT70 to its new location https://www.youtube.com/watch?v=Rq1UcOPrT70&feature=youtu.be

How to fix it

  • Replace your existing link with the updated URL provided in the warning and then double check the top of your page after saving to make sure the broken link alert is no longer displayed.
  • Remember, if these broken links appear on published pages, you'll need to save the changes you made to fix them as Published.

Linking to a page that isn't published yet

As you prepare draft content, you may create a link to a page that isn't ready yet. This problem will solve itself once your pages are published.

Broken links can also occur when published pages have links to unpublished pages. You can omit the link or update the linked page's status to Published.

What the alert looks like

The link checker is telling me there are multiple links to unpublished pages.

How to fix it

Before publishing, make sure all linked pages are published first.

Linking to domains that aren't accessible on the VA network

Occasionally the link checker will report a valid link as broken. This happens for domains that are not available from within the VA network.

How to fix it

You'll need to report the problem to the Drupal CMS help desk. They can help make sure the domain URL gets added to an allow list. Once the URL is on the allow list it won't cause false errors.

Typos in the URL or linked text

When you mistype a URL, the link will try to go to a page that doesn't exist. People who click on the link will likely see a “404: Page not found” error.

Mistakes that happen when you go to select (or deselect) the link text can also cause broken link reports. You might select a space or a single punctuation mark by mistake. The system will still create the link, but it will be hard for people to find. This can create accessibility issues.

How to fix it

The link checker will indicate the text that comes before the mistaken link. Go back and find the text in the rich text editor, then unlink it and try again.

Was this helpful?