How to report an intermittent bug

You have seen it three times this month, you cannot make it happen on purpose, and the form in front of you is asking for steps to reproduce.

File it anyway. What changes is only the middle of the report: the sequence somebody else can follow does not exist, and inventing one makes the report worse rather than longer. Expected and actual do not change, so everything in the bug report guide still applies, and the reproduction steps guide still governs the partial steps you do have. This page is about what goes in the gap.

The short version

• File it now, rather than waiting until you can make it happen on demand.
• A timestamp beats guessed steps. A time can be looked up. Invented steps cannot.
• Say how often as a count, not as "sometimes".
• Say since when, even when the honest answer is that you do not know.
• Say what was different the times it did happen.

Capture it while the tab is still open

The substitutes for steps are the three the bug report guide lists: a timestamp, an identifier that was on screen, and what was unusual. What is different here is when you collect them, and how precise the time needs to be. Get it to the nearest minute while you can still read the clock. A bug you can reproduce will still be there in an hour; this one will not, and the retry that works overwrites the only look you get.

Be literal about what you saw, and equally literal about what you did not see. All eight things "it doesn't work" can mean are still on the table, and you only get one look at yours, so settle which one it was while the screen is in front of you rather than from memory a week later. Paste the error text now. You cannot go back for it.

Keep the note even if you do not file straight away. If it happens again, a second sighting with its own time and identifier is worth more than describing the first from memory.

How often, said as a count

Give a number, and say what you were counting out of. "Four times since Monday, out of roughly forty uploads" is a rate. It helps the reader decide whether reproduction is worth an afternoon, and it sets the expectation before they start, so one passing attempt is not read as evidence that nothing is wrong.

The denominator is the half people leave out and usually the half they can supply: you know roughly how many invoices you uploaded this week. When you genuinely cannot count it, count the sightings you are sure of and describe the denominator loosely, as in "three times in a fortnight, and I do this most days". Even "three times, and no idea how many times it worked" carries information, because it says the failures are countable and the successes are not.

Since when, with no steps to offer

This is now the sentence doing the most work, because it narrows the search to whatever changed in the window. Three answers are honest and all three are worth writing down.

• A date or a week. "It started the week of 2 September."
• "First time I have used this feature." Then it may never have worked, which is a different investigation.
• "I do not know, I only started noticing." Write it anyway. It rules out a regression window nobody can support, and it says your count starts when you began paying attention rather than when the bug did.

The partial steps you do have

You cannot write steps that reproduce it. You can write the steps you took on the occasions it did happen, which is a different thing, and the whole difference is the label. Give the state you were in, the actions and the result, then one line saying what they are: "these are the steps from the three times it happened, not steps that reliably reproduce it".

That line heads off the expensive misunderstanding, which is a reader following unlabelled steps once, seeing them work, and concluding the steps are wrong. Inside the partial steps the reproduction steps guide still applies: start where the reader could start, and name the data rather than describing it.

Four places the pattern usually hides

A reply of cannot reproduce usually means something differed between your setup and theirs. The person trying can check their own side of that. Nobody at the other end can see your account, your data or your morning, so these four are the part only you can do.

• Who. One account, one role, one device, one colleague and not the rest of the team.
• When. A time of day, the first action after logging in, or after the page has been open a while.
• Which data. A particular record, an unusually large file, a name with an apostrophe or an accent in it.
• What else was running. A second tab, a slow or shared connection, a VPN, a release that went out that morning.

One sentence of answer changes the report: "it has only ever happened on the shared laptop" turns three sightings into something somebody can act on. If none of them match, say so, because ruling them out is also a finding.

What not to do

Do not hold it back until you can reproduce it. The evidence decays while you wait: times get rounded, identifiers scroll away, and the version you were on is upgraded from under you.

Do not invent steps. They send somebody down a route you never took, and when it behaves for them the disagreement is about your steps rather than the bug.

Do not call it random. Random is a claim about cause and you are not in a position to make it. It also invites everyone to stop looking for a pattern before anyone has looked.

Do not lead with your theory. Put it at the end, labelled as a guess. It is often useful and never a substitute for what you saw.

What happens to it after you file

With no steps to follow, the most promising thing left is whatever record the system kept while it was going wrong. That is what a time and an identifier buy: somewhere to look. Both are cheap on the day and awkward a fortnight later, which is the whole argument for filing before you have the full picture.

The follow-up questions tend to be predictable, so answer them in the report rather than waiting to be asked: the exact version, when it started, and anything the logs or the console showed. Those are three of the things WhatProblem asks about when they are missing, and none of them get easier to answer with time.

If the reply comes back as cannot reproduce, that describes what happened when somebody tried. It is a status, not a verdict on whether you saw it. The useful response is the next sighting, with its time and identifier attached.

A complete example

That report is no longer than an ordinary one. It is the same report with the steps taken out and a time, an identifier, a count and one observation put in their place.