How to File a Good Bug Report
A good bug report is the single biggest factor in how quickly we can fix your issue - for both humans on our team and the AI tooling we use to triage. Five extra minutes of writing can turn "doesn't work" into something we can act on inside one session.
This page is the canonical checklist. The same list is enforced as the post guidelines in our Discord #ask-for-help channel and as the fields in our GitHub bug report template.
The Checklist
When you file a TinaCMS bug, include all of the following that are relevant:
1. The exact error message
Copy-paste it, don't paraphrase. The exact string is what we grep for, and what AI agents pattern-match on. A report that says "React error" is much harder to act on than one that says "React Error #31: Objects are not valid as a React child".
2. Steps to reproduce
What you clicked, in order. Even a numbered text list is enough - you don't need a video.
The image insert is broken, it just crashes.
❌ Figure: Bad example - vague description we can't act on
1. Open TinaCMS admin2. Navigate to any page with an image field (e.g., a Hero Banner block)3. Click the image field → "Media Library" tab4. Select any image from the media library5. Click "Insert"
✅ Figure: Good example - numbered click-by-click sequence
3. Expected vs actual behaviour
A single sentence each is fine. Tells us whether you've hit a bug or a misunderstanding.
Expected: The selected image is inserted into the field and the src string is saved.
Actual: TinaCMS admin goes blank/white screen. Console shows React error #31.
4. Your environment - including anything non-default
This is the one most people forget, and the one that most often points us straight at the root cause. Include:
- Version of
tinacmsand@tinacms/cli - Framework (Next.js, Astro, Remix, etc.)
- TinaCloud or self-hosted
- Anything non-default - custom
MediaStore, custom auth, custom adapters, self-hosted setup, etc.
5. A way for us to reproduce
A minimal reproduction repo we can clone and run is the gold standard. npx create-tina-app@latest is a good starting point if you need a skeleton.
For Tina-specific issues
If your issue involves the schema or TinaCloud, also include:
- Relevant sections of your schema file (you don't have to paste the whole thing)
- Client ID - for any TinaCloud-related issue
A real-world example
Issue #6679 - React Error #31 when inserting image from Media Library with custom MediaStore is what a good report looks like in practice. It includes:
- The exact error string ("React Error #31: Objects are not valid as a React child")
- A numbered list of steps to reproduce
- The shape of the data being passed (object with keys
{id, src, filename, directory, type, thumbnails}) - The environment, including the custom GitHub-backed
MediaStoreadapter - A guess at the root cause
That report was investigated, fixed, tested and merged in a single session because every piece of the checklist was there. With a vague "images are broken" report, it would have sat untouched.
Where to file
- Discord -
#ask-for-helpin the TinaCMS Discord server. Best for "is this a bug or am I doing something wrong?" questions, and for community help. - GitHub Issues - tinacms/tinacms/issues for confirmed bugs. Our GitHub issue template prompts you with the same checklist as this page.
Why this works
The format isn't arbitrary. Each item maps to something a human or AI agent does when investigating:
Item | Why it matters |
|---|---|
Exact error | The grep target - points at the right file and line within seconds |
Repro steps | Tells us when the code path is taken |
Environment + custom adapters | The biggest source of "works for me but not for them" - calls out the variable to test |
Repro repo | Removes the gap between "we think we've fixed it" and "we've actually fixed it for you" |
Five minutes of your writing saves hours of back-and-forth, and lets the agents we use triage your report instead of waiting on it.