Skip to content

Reporting Bugs

smallketchup82 edited this page Oct 29, 2026 · 3 revisions

Report ZkMacOS problems in this project’s issue tracker. Do not send port-specific reports to the official Zero-K developers.

Before opening an issue

  1. Search existing issues and Known Issues for the same symptom.
  2. Note your app release and macOS version. Say whether you installed the DMG, used Homebrew, or built from source.
  3. Try the relevant troubleshooting steps. For graphics problems, record a comparison with the experimental graphics switches off; do not discard the failing settings.
  4. Write the smallest repeatable sequence you can find. If it is intermittent, say how often it occurs rather than calling it reliably reproducible.
  5. Preserve the relevant logs and screenshots before restarting or changing the scene.

What to include

Copy this into a new issue and fill in what you know:

Summary:

App release/build number:
Installation method: DMG / Homebrew / local build
Mac model/chip and RAM:
macOS version:
Display(s), resolution/scaling, fullscreen/windowed:

Steps to reproduce:
1.
2.
3.

Expected behavior:
Actual behavior:
Frequency / when it started:

Graphics preset and Retina mode:
MetalFX / macOS HDR / GPU sharing / DisplayLink / notchful fullscreen:
Game version, map, and match/replay details if relevant:
Relevant logs, screenshots, or crash report:
Workaround or comparison tested:

For a source build, include the central repository commit and relevant fork revisions. If a build fails, attach the failing stage’s log and the first actual error, not just the final “build failed” line. Building and Testing explains the log locations.

Find version information

Use the installed release label and, when needed, inspect the app without launching a game:

defaults read /Applications/Zero-K.app/Contents/Info CFBundleShortVersionString
defaults read /Applications/Zero-K.app/Contents/Info CFBundleVersion
sw_vers

Adjust the path if your app is installed elsewhere. For engine-version mismatches, also include the required version shown by the server and the engine version recorded in infolog.txt.

Share useful evidence

infolog.txt and log/ are under ~/Library/Application Support/Zero-K. Preserve the log from the failing session before another run replaces it. A screenshot or short recording is useful for invisible panels, incorrect scaling, notch placement, color/orientation bugs, and frame-pacing symptoms. For multiplayer problems, distinguish joining live, catching up, reconnecting and replay playback.

Review attachments for passwords, authentication tickets, account details and other personal data. Do not upload the whole Application Support directory. Do not attach private signing keys or a private replay without permission to share it. If redacting a detail would remove information needed to reproduce the problem, say so and arrange a private handoff with the maintainer.

A connection or a short test is not evidence of full multiplayer synchronization or long-session stability. Describe what actually happened, and include the point at which behavior diverged.

Optional Sentry reports

Use Settings → Telemetry → Report a Bug… to prepare attachments and open the structured GitHub issue form with environment details prefilled. Saved attachment defaults initialize each manual report; manual choices do not change those defaults. You can report on GitHub without a Sentry upload. Local development builds never upload to Sentry.

Read Telemetry for consent, attachments, collected data, privacy and reporting limitations. Sentry reports complement reproduction steps and do not capture every bug or prove its cause.

Clone this wiki locally