Issue Reporting Guide

Introduction

You've found a problem. We probably want to fix it. This guide will walk through what we need to fix it for you quickly. Following these steps is the easiest way to prevent it taking a lot of time for us to get what we need. The Factorio Access maintainers generally have other obligations such as jobs, and so we prioritize people who you help us to help you.

You have two primary ways to report issues. If you have a GitHub account, then click this link and fill out our issue template. Otherwise, our Discord has an issues channel.

Note that "make this feature better" isn't an issue. For example "I press this key and the game crashes" is an issue, but "let's change how items in the inventory are announced" is a feature request or enhancement. You not liking something doesn't make it a bug! We're certainly interested, but that's handled differently--just bring it up somewhere or open a GitHub issue using the new feature template, we'll ask you for what we need.

Basics

We'll want some or all of the following. Depending on how complex the bug is, we'll want more and more. If you know it's hard to make happen, give us a lot if you can. The more you can give us, the better:

• A detailed description of the issue
• If it's a crash, the error information printed by the game.
• Mod version
• Your save file
• A "repro".

The rest of this document will walk you through how to get this information for us. Mod version, a good description, and the error are absolutely required. Your save is very helpful. A repro is sometimes required.

Usually, we figure out what the real issue is and your goal is to give us an example of it that lets us make the problem happen easily. If we can make the problem happen easily, then we can know for sure that it's fixed.

Mod Version

For now this is kind of encoded in the release zip you used to install it and that makes things a bit tricky. If you've forgotten the version, here's how to get it.

• Go to your factorio directory.
• Open the mods folder
• Open the FactorioAccess folder or zip
• The version may be found in info.json: "version": "0.13.1",

Describing the Issue

Let's pretend that sometimes the game crashes when you build an assembly machine. Bad descriptions are things like "the game crashed today", "man building doesn't work". Good descriptions are things like "When I'm building and press left bracket to place the item, the game crashes sometimes", or "The mod likes to say unknown-key:build-assembly-machine". It's super important to say what the problem is, otherwise we'll have to ask you and wait on your response.

Getting the Error

If the issue is a crash, the game will print error information to the screen. For your own reference, you can use OCR to see what it is. Unfortunately, OCR breaks when it comes to giving us all the information that we need because it also includes lots of numbers and file paths, and these are often wrong or missing.

Instead, in your factorio folder, is a file factorio-current.log. Immediately after the crash happens, while the game is showing the crash, close the game and open this file in any text editor. Near the bottom, you will find some lines that look like this:

8.083 Error MainLoop.cpp:1404: Exception at tick 20358001: The mod Factorio Access Mod (0.13.1) caused a non-recoverable error.
Please report this error to the mod author.

Error while running event FactorioAccess::on_tick (ID 0)
Error when running interface function kruise_kontrol_updated.is_active: __Kruise_Kontrol_Remote__/script/remote.lua:75: attempt to call method 'is_idle' (a nil value)
stack traceback:
	__Kruise_Kontrol_Remote__/script/remote.lua:75: in function <__Kruise_Kontrol_Remote__/script/remote.lua:67>
stack traceback:
	[C]: in function 'call'
	__FactorioAccess__/scripts/kruise-kontrol-wrapper.lua:116: in function <__FactorioAccess__/scripts/kruise-kontrol-wrapper.lua:115>
	(...tail calls...)
	__FactorioAccess__/control.lua:2556: in function 'move_characters'
	__FactorioAccess__/control.lua:2400: in function 'on_tick'
	__FactorioAccess__/control.lua:2388: in function <__FactorioAccess__/control.lua:2386>
  10.224 Quitting: window closed.
  10.699 Goodbye

That's the part we need. If you are a fellow programmer, we're looking for the traceback and error message. If you don't know what that means, just copy everything down from the line above "Please report this error to the mod author.", in this example, start at and include 8.083 Error MainLoop.cpp:1404: Exception at tick 20358001: The mod Factorio Access Mod (0.13.1) caused a non-recoverable error.

The game replaces this file every time it opens so you must get it immediately. If you missed your chance, then there is a factorio-previous.log and that may contain it instead. Otherwise you'll need to make the error happen again.

We want to make this step easier, and will update this guide once that happens.

Getting Your Save

If you have saved since the game launched, then closing the game should cause the launcher to ask you if you want to name it. Say yes, then give it a name you'll remember like "bug".

Next, in your Factorio folder is a folder called saves. Go in there, and you will find a bunch of zip files. If you named your save bug, it'll be in bug.zip. That's the file we need.

The Repro

Sometimes a brief description just won't do. A repro, short for reproduction, is the programmer term for really detailed directions that will make the issue happen. What we do is figure out the why part, but you have to give us the what part.

This can be a bit hard to grasp, so let's do an example. Pretend that the issue is that placing assembling machines on transport belts causes a crash. When you see the crash, you probably don't know this yourself. That's fine! We'll figure that part out if you don't know it.

There's two steps to getting a repro. The first step is to figure out how you can make the problem happen reliably. Sometimes it's not going to happen every time, and that's okay, but if you can't make it happen then neither can we. The second step is to tell us what you did. For example, you might play the game until the building code crashes, then take your last save and try building a bunch of stuff until you find a way to tell us where to build what to make it explode.

here's a couple examples.

A completely useless repro is "build stuff and it'll break. No I don't have a save."

A useful repro is this. Put the assembling machine in your hand and save the game. Then hand that off to us and say "take this save and open it, press a three times,. then press left bracket".

Mostly that's where you'll stop and we'll figure out the rest, but the best possible repro is "start a new game, then place a transport belt and put an assembling machine on top of it". Why? Because while you may not know what the problem is, we don't have to figure out what the specific keys you pressed do or what's special about your save if you can say it that way. But these are hard! Before you can say something like that, you'll need to test it in a few different scenarios, otherwise you might as well have used the last example and left it to us. If you go this far and are wrong, we'll spend more time figuring out you were wrong than we will fixing the problem in a lot of cases.