CraftOS-PC

Getting Started

API Reference

Error Messages

This page details some error messages that may appear when using CraftOS-PC, and how to fix them.

An error occurred while opening the computer session

This error happens when a critical problem occurs when the computer session is being created. Usually this is a problem with the ROM or some other system-level issue. Here are some possible messages that can happen:

Message Description Remedy
Could not mount ROM The CraftOS ROM directory is missing. Make sure the rom folder is present in the CraftOS-PC installation directory. If using a custom ROM directory, make sure you're passing in the top-level folder that contains rom and bios.lua, and not the rom folder itself.
Could not mount debugger ROM The debugger support files are missing. This usually occurs when using a custom ROM. Make sure the debug folder is present in the installation/ROM directory. If it is missing from a custom ROM, you can copy it from the original ROM.
Could not load per-computer config: ... The computer's per-computer configuration file is corrupt. Back up and delete the <id>.json file from the config folder in the data directory.
Could not create new terminal An error occured while creating the terminal window for the computer. See below for more info on this error.

Could not create new terminal

This error can happen when creating anything that has a terminal attached, such as a computer, debugger, or monitor.

Message Description Remedy
Failed to create window The computer's terminal window could not be created. This is a rare issue, but it indicates some system issue that prevents CraftOS-PC from starting. On CraftOS-PC v2.3.1 or later, an extra error message is included that describes the issue better.
Failed to load font The font file could not be loaded. (Obsolete since v2.5.) This usually only occurs when using a custom font, including using the HD font. If using the HD font, make sure hdfont.bmp is present in the install/ROM directory. If using another custom font, make sure the file exists and is stored in BMP format. The path has to be an absolute path and accessible to the user that is running CraftOS-PC.
Failed to convert font The font bitmap could not internally be converted into the correct format. (Obsolete since v2.5.) This error is highly unlikely. On CraftOS-PC v2.3.1 or later, an extra error message is included that describes the issue better.

Failed to initialize renderer

This error can occur when an issue arises while setting up the video components. Usually this is caused by a missing font, but other situations may cause this to happen. (v2.5.5+)

Message Description Remedy
Failed to load font The font file could not be loaded. This usually only occurs when using a custom font, including using the HD font. If using the HD font, make sure hdfont.bmp is present in the install/ROM directory. If using another custom font, make sure the file exists and is stored in BMP format. The path has to be an absolute path and accessible to the user that is running CraftOS-PC.
Failed to convert font The font bitmap could not internally be converted into the correct format. This error is highly unlikely. On CraftOS-PC v2.3.1 or later, an extra error message is included that describes the issue better.

Computer runtime errors

These errors can occur while starting or running a computer.

Message Description Remedy
Couldn't load BIOS The BIOS file for the computer couldn't be loaded. This could be caused by a missing bios.lua file, or a compilation error in the Lua script. Make sure bios.lua exists in the install/ROM directory and is readable. Also check that there are no errors in the BIOS. If a compilation error occurred, an error message will likely be listed, and that can be used to diagnose the issue.
An unexpected error occurred in a Lua function An unprotected Lua error occurred in the BIOS, and the computer could not recover. This can also occur when using a top-level coroutine override (TLCO), at which point any errors are not protected and will cause this error. Make sure there are no runtime issues in the BIOS initialization sequence. If using a TLCO, make sure there are no errors in the running function.
Computer not responding A long-running task has ignored requests to terminate. You can choose to either force reboot the computer, or you can wait for the computer to respond. If you choose to wait, the error message will be delayed for another 20 seconds before appearing again.

Configuration loading errors

These errors occur when there is an error in one (or more) of the configuration JSON files. | Message | Description | Remedy | |---------|-------------|--------| | An error occurred while parsing the global configuration file | There is an error in the global config file at config/global.json. A description of what went wrong is included. | Check the global config file for errors at the line provided in the error message. If necessary, use a JSON checker website such as https://jsonchecker.com to find the error. | | An error occurred while parsing the per-computer configuration file | There is an error in the per-computer config file at config/<id>.json. A description of what went wrong is included. On CraftOS-PC v2.4 and later, the computer's ID is also included. | Check the config file for the computer being opened for errors at the line provided in the error message. If necessary, use a JSON checker website such as https://jsonchecker.com to find the error. |

Peripheral creation errors

These errors can occur when creating a peripheral.

Message Peripheral type Description Remedy
"side" parameter must be in the form of computer_[0-9]+ Computer The side parameter when creating the computer does not contain the ID of the computer. Make sure the side provided is either a string with "computer_" and then a number (indicating the computer ID), or just a number.
Failed to open computer Computer An error occured while creating the computer. An error message describing the issue should have appeared before this. See above for more information.
Could not start debugger session Debugger The debugger computer could not be opened. See above for more information.
Could not create new terminal Monitor The terminal window for the monitor could not be created. See above for more information.
Monitors are not available in headless mode Monitor A monitor was attached to the computer while in headless mode. Monitors cannot be created in headless mode. Restart CraftOS-PC with a different renderer to use monitors.

Peripheral runtime errors

These errors can occur when calling a method on a peripheral.

Message Peripheral method Description Remedy
Could not mount drive.insertDisk The requested directory to mount was not found. Make sure the path to the directory to mount exists and is readable.
Too many open channels modem.open The maximum number of open ports for a modem has been reached. Close some open ports, or adjust the maxOpenPorts config option.
Error printing to PDF printer.endPage An error occurred while writing the output. An additional error message is included to help diagnose the error.
invalid volume, invalid pitch, invalid speed speaker.playNote, speaker.playSound The specified value is out of range. Make sure the volume is in the range [0.0, 3.0], the pitch is in the range [0, 24], or the speed is in the range (0.0, 2.0].

Plugin errors

These errors can occur when loading incompatible plugins. They appear when starting the computer before the shell loads. Not all of these errors will cause the plugin loading to fail, but are just warnings.

Message Stops loading? Description Remedy (for plugin maintainers)
Missing plugin info No The plugin doesn't have any CraftOS-PC metadata. This usually happens when loading a standard Lua module as a plugin. Add a plugin_info function to your plugin as described in the plugin documentation.
Invalid plugin info No The plugin info function returned a non-table result. Make sure plugin_info pushes a table onto the stack passed to it with the plugin's metadata.
Old plugin API Yes The plugin was built for an older version of CraftOS-PC. Update your plugin to use the latest API version as listed in the documentation.
Missing API opener Yes The plugin is missing the function to load its API, or the plugin file is incorrectly labeled. Make sure the plugin has not been renamed, and make sure the plugin's loader function is labeled luaopen_<file>, where <file> is the name of the file sans extension.