Diagnosing Bugs – Divide and Conquer

Divide and conquer isn’t just for politics; it’s a solid approach for diagnosing or reporting bugs.

TD;RL

When reporting a bug or asking for tech support, make sure to provide ample information. Providing this info from the outset can greatly reduce the amount of ’email ping-pong’ or ‘forum ping-pong’ and lead to a quicker resolution.

The Situation

The information described below is not specific to InDesign, but as I live and breathe a lot of InDesign, I’ll use InDesign as an example application.

Imagine you are working with Adobe InDesign, and you perform a certain operation, and InDesign crashes (or hangs or exhibits some other unexpected behavior).

You restart InDesign, recover the document, try the same operation—and it happens again.

You might not know it, but you’re in luck! You found a repeatable problem.

As we all experience all too often, many crashes and hangs are not repeatable. Something odd happens, and when you want to show it to someone else, it works just fine.

Those kinds of non-repeatable bugs are the most frustrating: if you cannot reliably make the problem occur again, reporting it to the software developer (for InDesign that’s Adobe) will probably do little good. It’ll be classified as ‘cannot repeat’ and that’ll be the end of it.

A crash – that’s bad 🙁 .
A crash that is repeatable – that’s good 🙂 !

Mind you, non-repeatable crashes are not the end of the story. They might become repeatable when they happen frequently enough. It’s a matter of remaining vigilant and consciously take note of as many details as possible each time it happens.

After it happens a few times, if you pay attention, you might start noticing some kind of pattern that you did not notice before.

For example, ‘it’s always when I hold the Opt key while doing this or that’, or ‘it’s always when I place an image from that server’.

Keep your eyes and ears peeled, and with a little luck you might figure out what triggers the problem.

And eventually, the crash might become repeatable, and you can write out a little step-by-step process to make it happen.

“Open this document, while holding your breath. Then press the Opt key three times while shouting out ‘abracadabra’.”

Whittling down

Crash! Try again. Crash!

You might now be inclined to rush to the developer’s bug report site (e.g. Adobe’s User Voice), and file a bug report, or send an email.

However, that’s probably not going to do much good.

Yeah, it’s better than not filing a bug report at all, but you can do better, and improve the odds of getting a solution to the issue.

First of all, you might browse around and see if there are any other bug reports from other users that match the issue at hand.

If not, whittling down the crash will allow us to get a better idea of what the root cause might be, and in the process, you will often find a workaround.

E.g. “it crashes if I place a TIFF that’s more than 1024×1024 pixels” and then you find out that the issue does not occur if you use PNG instead of TIFF… Great! You’ve found a workaround.

Whittling down is the process of eliminating irrelevant factors from the context and collecting data points that will help finding a workaround and filing a good bug report.

I always put a lot of effort trying to whittle down any bug reports I file.

And as a software developer myself, I tremendously appreciate when one of my customers makes the effort to whittle down the problem before emailing me.

The worst nightmare for a software developer is to get an email from a frustrated and stressed user, often in all caps: “your software does not work”. It’s frustrating not being able to help them because of a total lack of context. What software? What platform? What version? What does not work?

Being forthcoming with info always helps getting the problem resolved faster.

First Steps

The first steps in whittling down involve platform, version and preferences.

Platform

What platform are you on – Mac? PC? x86 or ARM processor? Windows 10? Windows 11? How much memory… These parameters might or might not be important, and if you can try to figure out whether the problem is tied to the platform used or not, that’s very helpful.

Is it possible to try things out on a Mac instead of a PC? Or use InDesign 2025 instead of InDesign 2024? If you have a colleague or friend with a different platform, have them try it out and see if they can get the same repeatable crash. That kind of info is invaluable to help diagnose bugs.

Version

The second parameter is the version of the software you’re using. Nowadays with Creative Cloud it is fairly straightforward to figure out whether the problem is version-dependent, because the Creative Cloud Desktop application gives you access to older versions. You can do a bit of sleuthing yourself.

While you’re at it, make sure you have tried the latest version.

And if the problem turns out to be version-related, figuring out where between the successive version numbers the issue comes or goes is also invaluable.

E.g. “It crashes in InDesign 18.5 but not in 18.4” – that’s a solid gold data point!

Preferences

Many applications, including InDesign, store ‘semi-permanent’ preferences and cache files on your computer, and many bugs and crashes are tied to ‘something wrong in the preferences’.

You can try resetting your preferences (e.g. with InDesign, hold Cmd-Ctrl-Opt-Shift or Shift-Ctrl-Alt while re-launching the app) but that is quite dreadful. You’ll lose all your finely honed settings and will have to re-configure the application from scratch. Worse, there is also persistent stuff that is not cleared by a preference reset.

Instead, you can do a quick test. You do need to be master of your computer (i.e. have administrative privileges). If you are working on a computer that is managed by an I.T. department, then you’ll need to get the I.T. department involved to run this test for you.

Create a brand new user account on your computer. For example, my day-to-day account on my Mac is kris. I will then proceed to create another account, kris2. kris2 gets the same privileges as kris, but when I log out of kris and into kris2 I get a ‘clean slate’ to experiment with.

While logged in as kris2 I then try the repeatable crash and if it does not happen any more, I know it’s an issue tied to something in the ‘semi-permanent’ preferences for the kris account.

Knowing the results of this test is another important data point, and helps me decide whether there is any point in going through the pain and frustration of resetting the preferences in the kris account.

After it has served it’s purpose, I can delete the kris2 account.

Plugins

If you have any enhancements installed, like plug-ins or plugins or custom panels or scripts, try to see if the issue is related to the enhancement.

If possible, uninstall the enhancement and try again. Does the problem disappear?

Note: this does not mean that the enhancement causes the problem. You have to be very careful not to confuse correlation with causation.

In other words, the enhancement might be an innocent bystander, involved in causing the crash, without actually causing the crash.

Just recently, a user reported an issue with our free TextStitch plug-in.

I was in luck and the user was willing to do some whittling down on their end, and quickly came to the conclusion the core issue had nothing to do with TextStitch. They could also make the crash occur without any plugins installed.

Turns out, InDesign has a bug where creating a text thread between two text frames, in certain cases will cause an immediate crash. This crash also occurs when manually linking the frames, while TextStitch is not even installed.

TextStitch was but an innocent bystander. Because TextStitch needed to automatically create threads, it inadvertently tried to create the ‘impossible’ thread between two text frames, causing InDesign to crash.

The obvious, yet incorrect diagnosis was to blame TextStitch, where the real bug was in InDesign.

Divide and Conquer

The next part of the process is to try and write up a simple step-by-step process that any tech support person or developer can follow and see the crash for themselves.

This often involves a particular document or image.

In the case of InDesign the document that is involved in the crash might be large or confidential, and you cannot attach that particular document to your bug report.

Try a New Document

The first thing to try is to build a brand new document, and see if you can make the crash occur with it.

Create a new document, put in some text, maybe some images. Can you make the issue occur? If so, you’ve got a good sample document to attach to the bug report.

Try Copy-Pasting stuff

If a new document does not do the trick, try copying a few elements from the problematic document into a brand new document.

I’ve often found that ‘trouble travels’. Sometimes the issue is ‘attached’ to a text frame or image frame or style sheet, and copy-pasting stuff into a new document is enough to set up a small new document that also exhibits the issue.

Try the IDML round-trip

In the case of InDesign, we also have a secret weapon: the IDML file format.

Not many people know this, but behind the scenes, an IDML file is really a script.

What InDesign does when you save a document as IDML is to convert your document into a series of instructions: “Create a new page. Place a text box of size xyz at position pqr. Insert the text ‘bladibla’. Format the ‘bla’ with Comic Sans 12…”

An IDML file is just a cookbook with instructions on how to re-create your document from scratch.

When you open an IDML file, InDesign will execute all the instructions, and rebuild a brand new document from scratch.

That is why older versions of InDesign can open IDML files created by newer versions of InDesign: they will simply follow the instructions.

Normal .indd files are like elefants, and they have long memories, and hold grudges.

Often .indd files have passed through many versions of InDesign (e.g. originally created in CS6, then upgraded to CC 2019, then upgraded to 2024).

They hold on to a ‘memory’ of that chequered history. If one of those past InDesign versions had bugs, those bugs might leave weird problems embedded in the .indd file.

IDML to the rescue: saving a document into the .idml format, then re-opening and saving gets rid of all that past history: we’re rebuilding the document from scratch, and all those repressed memories disappear.

Round-tripping your document through IDML is always a good move!

Finally, Divide and Conquer

If we’ve gotten to this point, nothing has helped, and we’re still stuck with a document that has some issue somewhere.

The next step is to do ‘successive halving’. Do this on copies of the document (preferably after an IDML round trip). Keep the original safe!

What comes is not scientific: just delete a bunch of stuff. You might need to try different deletion strategies until you hopefully hit the right one.

Open the starting document, and delete about half of the content.

This might be ‘half of the spreads’, or ‘half of a long story’, or ‘half of the styles’.

The main thing is that you delete a lot of info, and make the document about half of the original’s size. If you delete pages, you might also need to delete text from long stories – otherwise, there might be a lot of overset text in the ‘halved’ document.

Then save the document. That’s ‘exhibit-A’

Open the same starting document again, and delete the other half of the content.

Save this document. That’s ‘exhibit-B’.

Now try the repeatable crash on both exhibit-A and exhibit-B.

If the problem disappeared in both of them, go back and try a different size reduction strategy (e.g. delete text instead of deleting pages).

If the problem has moved into either exhibit-A or exhibit-B or still exists both, pick one of the halved documents that has the issue, and repeat the halving strategy – this will give you exhibit-A-A or exhibit-B-A or whatever.

Keep on halving, retracing your steps, halving… as needed and try to create the smallest possible document that still causes the crash.

Once you get to that point, it often becomes apparent what the underlying cause might be. You might find it’s related to text reflow in particular text frames, or a particular image frame with particular settings.

By now, with a little luck, you might have figured out how to work around the bug and you now have a small document and a concise step-by-step procedure to make the crash happen.

You’re ready to file a bug report that has better odds of being actioned!

Quick Checklist

  • Exact steps you took before the crash
  • Platform (Mac/Win/Operating System…)
  • Version (InDesign 20.0, InDesign 18.5,…)
  • Did you try turning it off and on again
  • Did you try resetting your preferences
  • Attach screenshots
  • Report any error messages
  • Provide as much info as you can. Context is everything!
  • Attach a reduced-size sample document

For Creative Cloud apps, head to:

https://helpx.adobe.com/x-productkb/global/how-to-user-voice.html
https://community.adobe.com/

If you find this helpful, make sure to give me a positive reaction on LinkedIn! I don’t use any other social media platforms. My LinkedIn account is here:

https://www.linkedin.com/in/kristiaan/