How to write a bug report when staging fails but production works

A staging-only bug report should compare configuration, data, build version, and dependency targets before treating the failure as a code defect.

Staging is often similar to production but not identical. It may use a different database snapshot, feature flag, payment mode, callback URL, object storage bucket, search index, queue, email provider, or third-party API credential. A bug that appears only in staging can be caused by any of those differences, even when the application code is the same.

Write the report in two columns. In the first column, capture the staging request: URL, account type, feature flag state, build version, environment variable shape without secrets, dependency target, and first error line. In the second column, capture the same facts from production or another passing environment. The point is not to expose secrets. The point is to make the shape of the environment comparable.

Then describe the data difference. Is the staging record old, anonymized, partial, migrated, or missing a required relation? Does production have a webhook that staging never receives? Does staging point to a sandbox provider with different validation rules?

A good report ends with the smallest reproduction path and the most likely difference. That gives the next developer a concrete place to inspect instead of a vague claim that staging is broken.

How to write a bug report when staging fails but production works

// COMMENTS

ON THIS PAGE