These are the docs for 13.7, an old version of SpatialOS. The docs for this version are frozen: we do not correct, update or republish them. 14.1 is the newest →


Logging with the SpatialOS CLI

The SpatialOS CLI outputs information to two places: to the console and to spatial.log (in the current working directory).

The console

By default, the console shows information messages, warnings and errors. You can increase or decrease the amount of information shown in the console by adding the --log_level option.

For example, use --log_level=warn to show only warnings and errors in the console.

The log files

The log files (for example logs/spatial_<date_time>.log) show information messages, warnings, errors, and additional debugging information. They always contain all this information, regardless of the --log_level value you use in the console. Each file contains all the logs for a given SpatialOS CLI invocation. We keep the 20 most recent log files.

If you ask on the forums about a problem, make sure you send your log file along with your question.

Changing log file location

You can change the location of the log files using the --log_directory command line option. Set the value to be the path to the directory you want to use. For example:

spatial worker build --log_directory=./temp

Cloud deployments

For cloud deployments, SpatialOS outputs all logs to a web-based logging interface available from each deployment’s overview page:

Logs In the Console

This interface provides an easy way to explore logs:

Logs Interface

To filter by time, select part of the timeline:

Logs Interface

Or click on the start or end date to open a more detailed time period picker:

Logs Timepicker

Drag a section of the timeline to filter by time, and use the sidebar to filter by:

  • Message contents
  • Log level: INFO, WARN, ERROR
  • node_name
  • logger_name

Each log can then be expanded and its contents copied.

Finally, note the nifty Gmail-like keyboard shortcuts!

Logs Keyboard Shortcuts


Logs are retained for 9 days and then deleted.

Usage limits

The small, medium, and large game templates are deprecated and we will remove them in a future release. If you’re currently using one of them, you need to start using one of the templates listed in the table of game template sizes and prices instead.

You can still use SpatialOS for free - see Free tier for details of which templates you can use.

User logs from cloud deployments are subject to usage limits. The usage limit for all templates is 6000 messages per minute.

If you reach the usage limit, you’ll see the log message LOGGING RATE LIMITED - DROPPING LOGS. When the usage limit is reset, you’ll see the log message LOGGING NO LONGER RATE LIMITED.

Runtime log messages do not contribute to your usage limit.

Launcher logs

Logs for the Launcher can be found at:

  • Windows - C:\Users{username}\AppData\Local\SpatialOS\Launch\logs
  • Mac - /Users/{username}/Library/Application Support/SpatialOS/Launch/logs

Interpreting logs

The logs have entries of levels Info, Warning, and Error. Roughly, these mean:

  • Error

    These always indicate something going wrong. A single log entry of this type should be grounds for concern and should be investigated and resolved.

  • Warning

    These indicate that, possibly temporarily, the application was in an unexpected state. However, the application is intended to recover from these states autonomously. As such, warnings are only cause for concern if they are sustained over time, or if they occur together with errors.

  • Info

    These don’t indicate that anything is going wrong and shouldn’t be cause for concern. By default, these aren’t shown when running locally. You can turn the log level up or down by passing -DFABRIC_LOG_LEVEL=<level> as a JVM argument when running locally, where <level> is one of DEBUG, INFO, WARN, or ERROR.

Search results

Was this page helpful?

Thanks for letting us know!

Thanks for your feedback

Need more help? Ask on the forums