Submitting Bug Reports

Bug reports are the core of Bugnet. Players submit them via the in-game SDK widget, and developers manage them through the web dashboard. Every report captures the information your team needs to reproduce and fix issues quickly.

Each bug report includes the following fields:

• Title — A short summary of the issue
• Description — Detailed explanation of the problem
• Steps to reproduce — How to trigger the bug consistently
• Expected behavior — What should have happened
• Actual behavior — What actually happened
• Platform — The OS or device where the bug occurred
• Game version — The build version the player is running
• OS info and device info — Operating system and hardware details
• Screenshot (optional) — Captured by the SDK when screenshot capture is on
• Reporter name, email and Steam ID (optional) — Links the report to a player record for follow-up
• Metadata and attachments (optional) — See Custom Metadata

Reports can arrive in four ways:

1. SDK widget — Players open the in-game overlay and fill out a report form without leaving the game
2. SDK auto-capture — The SDK files errors and crashes itself, with the stack trace and recent logs
3. Public API — Anything holding the project API key can submit via POST /api/bugs/submit (this is what the SDKs call)
4. Dashboard or REST API — Team members create reports from the dashboard, or with a session token via POST /api/projects/:slug/bugs

When bug grouping is on for the project (the default), a report whose title exactly matches an existing report is stacked onto it as another occurrence instead of creating a new bug. The occurrence count shows how often it has happened, and each occurrence keeps its own platform, version, device and description.

# Create a bug report as a team member (session token)
POST /api/projects/:slug/bugs
{
  "title": "Camera clips through walls in Level 3",
  "description": "When moving into the corner near the waterfall...",
  "steps_to_reproduce": "1. Go to Level 3\n2. Walk to the waterfall\n3. Push into the corner",
  "expected_behavior": "Camera should stay behind the player",
  "actual_behavior": "Camera clips through the wall geometry",
  "category": "visual",
  "priority": "medium",
  "platform": "Windows",
  "game_version": "1.2.0"
}

Categories & Priority

Bug Categories

Bugnet organizes bugs into 8 categories so your team can quickly identify the type of issue and route it to the right person:

Priority Levels

Four priority levels control triage order and help your team focus on the most impactful bugs first:

Priority can be set when a bug is submitted and changed at any time by team members. Auto-Triage (Studio plan and above) can automatically suggest a priority based on the report content and player context.

Status Workflow

Bugs follow a status lifecycle that tracks them from initial report through resolution. Each status represents a distinct phase:

Status Transitions

Bugs typically move through statuses in this order: open → in_progress → resolved → closed. However, any team member with the appropriate role can change a bug's status to any other status at any time. Common transitions include:

• open → in_progress — A developer picks up the bug and starts working on it
• in_progress → resolved — The developer applies a fix and marks it for verification
• resolved → closed — QA or the reporter confirms the fix works
• resolved → open — The fix didn't work; the bug is reopened
• open → wont_fix — The team decides the behavior is intentional or out of scope

Who Can Change Status

Changing a bug’s status needs the bugs.edit permission, which owners, admins and members all have by default. An owner or admin can revoke it for individual members on the Team page. Players cannot change a bug’s status.

Notifications

A status change emails every other member of the project who has status change emails turned on (see Notification Preferences), and fires the bug_updated webhook and Discord notification if you have them configured. The team member who filed the bug from the dashboard also gets a status-update email. Players who reported through an SDK or the web form are not emailed, even if they left an email address.

Assignment

Assign bugs to specific team members to establish clear ownership and accountability. Assignment ensures every bug has a responsible developer and prevents issues from falling through the cracks.

• Assign from the dashboard — Open a bug and select a team member from the assignee dropdown
• Permissions — Assigning needs the bugs.assign permission (on for every role by default). Any project member can be the assignee
• Email notifications — An assignment emails the project’s other members who have assignment emails turned on
• Reassignment — Bugs can be reassigned at any time; each change is recorded in the activity log
• Unassigned bugs — Find them with GET /api/projects/:slug/bugs?assigned_to=unassigned

# Assign a bug to a team member
PATCH /api/projects/:slug/bugs/:number
{
  "assigned_to": "user-uuid-here"
}

Comments & Activity

Comments

Comments let your team discuss bugs, share additional context, and coordinate fixes. There are two kinds:

• Public comments — Shown on the bug’s page in your public tracker if you have one, so players can see progress
• Internal comments — Visible only to team members. Use these for technical discussion, debugging notes, or internal coordination that players don't need to see

Comments support Markdown formatting, including bold, italic, code blocks, and links. Team members can also reply to bug notification emails to add comments directly from their inbox without opening the dashboard.

# Add a comment to a bug
POST /api/projects/:slug/bugs/:number/comments
{
  "body": "I can reproduce this on Windows 11. Looks like a Z-buffer issue.",
  "is_internal": true
}

Activity Log

Changes to a bug are recorded in its activity log. The log tracks:

• Creation — When the report was filed
• Field changes — Status, priority, category and visibility (private/public)
• Assignment changes — When a bug is assigned or reassigned
• Comments — When a comment is posted
• Attachments — When a file is added
• Deletion — When the bug is deleted

Each activity entry shows who made the change and when it happened, so your team always has full visibility into a bug's history.

File Attachments

Attach screenshots, log files, save files, and other documents to bug reports to provide additional context for your team. Visual evidence and crash logs are often the fastest way to diagnose an issue.

• SDK screenshots — When a report is submitted and the project’s Screenshot Capture setting is on, the SDK captures the current frame and attaches it
• SDK file uploads — Every SDK can submit additional files (text, image, video, or JSON — e.g. logs, save files, or a screen recording) alongside a report. Pass them to the report call and the SDK base64-encodes and uploads them automatically (up to 10 files, 10 MB each). See the SDK reference for per-engine examples
• After the report — Upload more files to a report the SDK just filed (for example a full log after an auto-captured crash) with POST /api/bugs/:id/attachments and the API key
• Manual upload — Team members can use the Upload button in the bug detail view (10 MB per file)
• Limits — Only text, image, video and JSON files are accepted; the type is detected from the file contents. Uploads count toward your plan’s upload limit
• Access — Files are served from /api/files/… URLs that contain a random, unguessable ID. Anyone who has a file’s URL can open it, so avoid attaching secrets such as passwords or access tokens

Custom Metadata

Reports can carry an optional metadata field — a free-form JSON object you attach via the SDK or the public API. Use it to capture structured context that doesn't fit the standard fields: the active quest, feature-flag state, the player's hardware tier, a transaction ID, or anything else your team needs when triaging. The metadata is stored with the report and returned on the bug detail endpoint.

{
  "title": "Quest reward never granted",
  "description": "Finished 'The Long Road' but got no XP.",
  "metadata": {
    "quest_id": "long_road",
    "build": 1423,
    "flags": ["new_quest_system"]
  },
  "attachments": [
    { "filename": "player.log", "mime_type": "text/plain", "data": "<base64>" }
  ]
}

Bulk Operations

When managing a large number of bugs, bulk operations let you act on up to 100 reports at once. Select bugs in the bug list using the checkboxes, then choose an action from the toolbar.

Available bulk actions:

• Change status — Move multiple bugs to a new status at once (e.g., close all resolved bugs after a release)
• Change priority — Reprioritize a batch of bugs simultaneously
• Change category — Recategorize a batch of bugs
• Delete — Delete the selected bugs

Through the API, PATCH /api/projects/:slug/bugs/bulk can also set the assignee and visibility, and DELETE /api/projects/:slug/bugs/bulk deletes in bulk.

Bulk operations are available from the bug list view in the dashboard. Select the bugs you want to modify using the checkboxes on the left, then use the bulk action toolbar that appears at the top of the list.

Upvoting

Players can upvote bug reports they have also experienced, helping your team understand how widespread an issue is and prioritize accordingly.

• Upvote count — The number of upvotes is displayed in both the bug list and the bug detail views
• Prioritization signal — Bugs with more upvotes are more impactful and should generally be addressed first. Sort by upvotes to see the most-reported issues at a glance
• Public bug tracker — If you have enabled the public bug tracker for your project, players can browse and upvote existing bugs directly from the public page, reducing duplicate submissions
• One vote per player — Each voter counts once per bug. Voters are identified by the SDK’s player ID when one is sent, otherwise by IP address, so players sharing a network may share one vote

Duplicate Detection

Duplicate reports fragment the information your team needs. Bugnet reduces them in three ways:

• Grouping — With bug grouping on (the default), a report whose title exactly matches an existing one in the project is stacked onto it as an occurrence. Most repeat crash reports from the SDK land here. Stacked occurrences can be split back out into their own report
• Possible duplicates on submit — The response to POST /api/bugs/submit lists up to three open reports with similar text in possible_duplicates
• Similar-bug search — GET /api/projects/:slug/bugs/similar finds existing reports whose text matches a title, so you can check before filing

When you spot a duplicate in the dashboard, Mark as duplicate closes it with a comment linking to the original.

# Find similar bugs before filing
GET /api/projects/:slug/bugs/similar?title=Camera+clips+through+walls

# Response: matching reports with report_number, title, status, priority and created_at

Search & Filtering

Bugnet provides powerful search and filtering tools to help you find exactly the bugs you are looking for, even across projects with hundreds or thousands of reports.

Full-Text Search

Search across bug titles and descriptions using the search bar at the top of the bug list. Search matches whole words and is case-insensitive; add * to match a prefix (e.g. collis*).

Filters

The bug list can be narrowed by:

• Status — open, in_progress, resolved, closed
• Label — Any of the project’s labels
• Source — Reports from players and your team, or reports Bugnet filed itself

The API accepts more: status (including wont_fix), priority, category, assigned_to (a user ID or unassigned), label, source and q. See Bug Endpoints.

Saved Filters

Combine multiple filters into a saved filter that you can reuse with one click. Saved filters are personal to you. See the Project Management docs for more details on creating and managing saved filters.

Sorting

Sort your bug list by any of the following fields:

• Created date — Newest first (the default)
• Updated date — Most recently active bugs first
• Priority — Critical bugs at the top
• Upvotes — Most-reported issues first

Bug Dependencies

Some bugs are related to or depend on other bugs. Bugnet lets you create dependency relationships between bugs so your team can plan the fix order and understand how issues are interconnected.

Dependency Types

• Blocks — This bug must be fixed before the linked bug can be addressed
• Blocked by — This bug cannot be fixed until the linked bug is resolved

Working with Dependencies

• Create dependencies — Open a bug’s detail view and link another bug in the same project by its report number
• See links — The detail view lists the bugs this one blocks and is blocked by, with their current status
• Fix planning — Use dependency information to plan your sprint or patch schedule. Bugs that block many other bugs should generally be fixed first

# Bug #12 blocks bug #15
POST /api/projects/:slug/bugs/12/dependencies
{"related_number": 15, "relationship": "blocks"}