Cross-reference Problems – Troubleshooting
You may sometimes experience that one or more cross-reference fields in a document do not show the correct content. You may experience cross-reference fields that are not updated even if you changed the referenced item, e.g. a heading. The problem may also be that one or more fields refer to section no. 0 or a wrong number. Finally, the problem could be that one or more fields contain a lot of text where you expected a reference to a heading only. This article explains how these errors occur and how to manually repair and prevent them.
The article also introduces you to DocTools CrossReferenceManager – an advanced Word add-in that makes the work with cross-references much faster and easier and that can help you automatically repair and prevent cross-reference problems in the future.
Word add-in ready for use
DocTools CrossReferenceManager - advanced add-in for Word
DocTools CrossReferenceManager is an advanced Word add-in that makes it easier and smarter than ever to work with cross-references in Word.
The add-in works with Microsoft Word 2010 and newer versions on PC/Windows.
DocTools CrossReferenceManager lets you do everything you can do using the built-in cross-reference functionality of Word easier and faster. In addition, DocTools CrossReferenceManager includes smart and efficient cross-reference features that are not found elsewhere.
For example, you can save language-specific custom cross-reference texts that contain placeholders for multiple cross-reference fields and insert the text, including all the cross-references, with a single click. See the example below (field shading is turned on to make it easy to identify fields):
Among the features are also special tools for detecting and handling cross-reference errors:
You can access the functionality of the add-in from a custom tab in the Ribbon.
How to get the DocTools CrossReferenceManager add-in
This advanced add-in is not free but the return on investment is almost immediate. It will make all your future work with cross-reference faster and easier.
Click the button below to learn more about DocTools CrossReferenceManager or to buy the add-in.
You can try DocTools CrossReferenceManager risk-free for 7 days.
Manual troubleshooting of cross-references
Read below if you want to manually find and fix the cross-reference problems instead of letting the DocTools CrossReferenceManager add-in help you.
General tip about working with fields in documents
A cross-reference is a field, i.e. set of codes that instructs Microsoft Word to automatically insert material into a document. The material can be text, page numbers, section numbers, graphics, etc.
Fields can be shown with gray shading on the screen so that it is easy distinguish fields from normal text. Note that field shading does not print. Field shading can be turned on via Tools > Options > View tab. You can select to have field shading shown Never, Always or When selected. See the illustration below.
In case of Microsoft Word 2007, you will find the Field Shading option as follows: Office button > Word Options > Advanced category > Show document content group > Field shading.
In case of Microsoft Word 2010 or later version, you will find the Field Shading option as follows: File > Options > Advanced category > Show document content group > Field shading.
I recommend that you always show field shading when working with documents that contain fields.
If you cannot see the fields, you risk to make changes that are lost when you update fields. Setting field shading to Always also makes it much easier to find cross-reference problems, if any.
If you use Microsoft Word 2007 or later version
Note that the videos have been created using Microsoft Word 2003. The videos show the Bookmark dialog box. In Microsoft Word 2007 or later version, you can open the Bookmark dialog box via Insert tab > Links group > Bookmark.
Problem 1 – cross-references are not updated
Situation: You have made changes to one or more headings or other items that are cross-referenced in the document. However, the cross-reference fields still show the old text even if you update all fields.
View the video below for an explanation of how the problem occurs and how you can solve it. The video also explains what to do in order to prevent such errors. The key to the problem is to be found in the way you edit cross-referenced items.
View video - learn how to solve the problem
Problem 2 – cross-references refer to section no. 0 or show wrong numbers
If the problem occurs in relation to a cross-reference to a numbered paragraph in a table, see also Problem 4 below.
Situation: One or more cross-reference fields that should have referred to a heading number (or another numbered item) refer to section no. 0 after updating fields. Alternatively, one or more fields refer to a wrong number after updating fields.
View the video below for an explanation of how the problem occurs and how you can solve it. The video also explains what to do in order to prevent such errors. As for problem 1 described above, the key to the problem is to be found in the way you edit cross-referenced items.
View video - learn how to solve the problem
Problem 3 – cross-references contain too much text
Situation: One or more cross-reference fields that should have referred to the text of a heading or another item contain too much text after updating fields. You may even see e.g. tables or pictures included in a cross-reference.
View the video below for an explanation of how the problem occurs and how you can solve it. The video also explains what to do in order to prevent such errors. As for problems 1 and 2 described above, the key to the problem is to be found in the way you edit cross-referenced items.
View video - learn how to solve the problem
Problem 4 – cross-reference to a numbered paragraph in a table refers to number 0 or a wrong number
Situation: You insert a cross-reference to a numbered item in a table. Instead of showing the number you selected, the cross-reference shows 0 or a wrong number after updating fields.
See the two illustrations below. In both illustrations, the cross-references that show 0 and A refer to the yellow 1. and 2. in the table and should have shown 1. and 2. Formatting marks are shown so you can see that the numbered paragraphs in the yellow column/paragraphs contain no text after the number and tab.
This problem is caused by a bug in Word that exists in all Word versions at least since Word 2003. The problem occurs if you insert a cross-reference to a paragraph for which the following is true:
If all rules above apply, Word creates a wrong bookmark for the cross-reference as explained and illustrated below. Notice that the rules apply to the two examples illustrated above. In the first example, the numbered paragraphs are in the second column. In the second example, the numbered paragraphs are in the first cell in the row.
When you insert a cross-reference to a numbered item, the _Ref bookmark Word creates should enclose the text of the target paragraph only. But when the rules above apply, Word creates a bookmark that encloses the entire row in which the paragraph is found and the cross-reference will show the number of the first paragraph in the bookmark. This means that the inserted cross-reference will show whatever number is found in the first paragraph in the first cell in the row instead of the number you selected. If the first paragraph in the first cell isn't numbered, the cross-reference will show 0. Therefore, the cross-references in the illustrations above show 0 instead of 1. and A instead of 2.
If a cross-referenced, numbered paragraph is the first paragraph in the first cell in a row, the bookmark would still be wrong but you wouldn't notice because the cross-reference would fetch the number for the correct paragraph in that situation.
If a cross-referenced, numbered paragraph is not the first paragraph in the first cell in a row, but if the first paragraph in the first cell in the row happens to be numbered with the same number as the selected target for the cross-reference, you wouldn't notice the problem either but the cross-reference would actually show the number from the wrong paragraph.
The bookmark problem is illustrated below. The field codes of the first REF field are shown (above the arrow) and the bookmark has been selected in the Bookmark dialog box:
How to prevent or correct the problem
In order to prevent the problem with wrong cross-references to empty, numbered paragraphs in tables, Word must be forced to create correct _Ref bookmarks. You can solve the problem as follows:
The space will cause Word to create a correct bookmark and thereby a correct cross-reference. You could add any other character than a space but a space will not be visible in the final document. See the illustrations below:
The solution with the space is only illustrated with one of the two examples above but it will work in all cases.
If you have already inserted cross-references that are wrong due to wrong bookmarks, the easiest solution is most likely to correct each instance by adding a space in the target paragraph as illustrated above, then delete the wrong cross-reference and create a new cross-reference.
Alternatively, you would have to correct each of the wrong bookmarks. To correct the bookmarks, follow the principles shown in the videos included with Problem 1, Problem 2 and Problem 3. You can manually delete the old and wrong bookmarks if you want to get rid of those bookmarks. They do not harm but they clutter the collection of bookmarks.
Another way of repairing wrong cross-reference fields
The videos included with Problem 1, Problem 2 and Problem 3 above describe how to correct errors in cross-reference fields by correcting the _Ref bookmarks to which the cross-reference fields point.
Alternatively, you could delete each incorrect cross-reference field and replace it by a new field. However, this would leave the wrong _Ref bookmarks in the document and thereby clutter the collection of bookmarks.