Troubleshooting the App

Desktop / Laptop App Installation

Your operating system has checks to prevent malicious software being installed and run on your machine. The Running Reality app is cryptographically signed to assure you of our identity and to meet these requirements. However, the app can still trigger warnings depending on your computer's specific settings. See details below for Microsoft Windows and Apple MacOS.

Microsoft Defender is blocking the installation

On Windows 10 (and newer), a subsystem of Microsoft Defender known as SmartScreen may give a warning for the Running Reality installer. Clicking 'More info' in the warning window makes a button appear to 'Run anyway' which lets you proceed.

More about Microsoft Defender

On Windows 11, an additional system known as Smart App Control may block running the app. Additional information about this system can be found here:

More about Microsoft Smart App Control

On Windows 7, 8, and 9, Microsoft Defender, known previously as Windows Defender, can give warnings about downloaded software. If you right-click on the installer file, then select 'Properties' from the menu, you will get the window below. You can select the check box to 'unblock' the installer from running.

Apple's MacOS Gatekeeper is blocking the installation

Gatekeeper may be configured to only allow applications from Apple's App Store or to require a second-tier of app review known as notarization. To open an app that you downloaded directly, like Running Reality, right-click on the installer, select "Open" from the pop-up menu, then again select "Open" from the dialog box. We are working as quickly as we can to update Running Reality to meet the notarization requirements so Apple can check the app.

If your Mac still won't let you open and run the installer, you may have to change a system setting to allow non-App Store apps. See the figure below. Running Reality is an "identified developer."

More about Apple Gatekeeper
I clicked the download button and nothing happened?

Your web browser downloaded the app's installer file, but did not install it. At more than 100Mb in size, the file might take a minute or five to download. You will need to double-click on the installer file to perform the installation.

I'm not sure if my machine is powerful enough?

The system requirements are below:

I ran the installer and nothing seems to have happened?

You may not have sufficient system resources to run the app, like too little free disk space. The installer may have had an error and quit without completing the installation. This will leave a half-installation in place, with corrupted files. See Finding the App's Files below on this page to find and delete the files of the half-installation.

I opened the DMG installer file on my Mac and it vanished. Where did it go?

There are reports that sometimes the window opens behind all your other windows. There is a MacOS Finder bug where DMG windows sometimes open in the back. The easiest thing is to go find the window, using Mission Control, Spaces, or just minimizing windows. Restarting the Finder is the harder fix.

My Mac says it can't start apps downloaded from the Internet?

Apple by default only allows apps from the Mac App Store. However, Running Reality is digitally signed by an Apple identified developer certificate and should be able to run.

Learn more about Apple's security
Learn more about our security
I get a "Can not start the JVM" error with suggestions about my antivirus software or a .vmoptions file.?

This means that the installer, launcher, or uninstaller can not start. The top causes of this error are:

The app starts, begins to load, then the screen goes black and the app quits without warning. What happened?

This means that your computer does not have enough memory to run the app. The app requires about 6Gb of memory. If your computer has only 8Gb of memory or less, there may not be enough free memory to run the app.

I have an older Windows operating system, and Running Reality won't start?

On Windows XP, 7, and 8 machines some web browsers use older 32-bit technology for plug-ins, forcing the 32-bit version of Java to be used. Unlike the 64-bit version of Java, the 32-bit version limits the maximum memory allocation to Java programs about 1.2GB to 1.5GB of memory. We can no longer support the 32-bit version. You may be able to install the normal 64-bit version of Java anyway, along side the 32-bit version that your web browser downloaded by default.



Mobile / Phone App Installation

On my iOS device (iPhone or iPad), the automatic installation didn't work? Can I manually install it?

Yes, to put Running Reality on your phone you can use these manual steps:

On my Android device, the automatic installation didn't work? Can I manually install it?

Yes, to put Running Reality on your phone you can use these manual steps:

Learn more at Google's Android support page


App Setup

I got the app running, but the map is totally blank?

The app should first load the low-resolution map, then all the objects (nations, ships, armies, etc.), and then download the high-resolution map in the background. However, sometimes, the objects wait until the high-resolution map has downloaded, which means the software appears to hang for a little while.

Be sure that you are not zoomed in too far to see anything, such as being zoomed in to the center of the ocean so the whole screen is blue.

I got the app running, but the map is really blurry and low resolution?

The higher-resolution maps take longer to load. The rest of the app loads first, then the high-resolution maps appear after the world model is finished loading from disk.

Also see the Frequently Asked Questions


Running the App

How do I learn more about using the app?

The Running Reality app has more tools than the web version so that you can edit history directly, contribute to the Running Reality project, or work with your own historical research in your own data files.

See the documentation
How do I view / edit / analyze my own historical data?

Running Reality can work data from a range of digital history data sources, in their native format. You can view the data, perform a number of analyses on that data, view the data, or convert it from one type to another. Depending on the source, it can display it as a layer over top of the world map, or it can convert it to history data that is incorporated into the world model, thereby adjusting the map. Data sources can be geospatial or geotemporal, but they do not have to be. A data source can be a PDF of an article about a relevant topic.

Learn about data sources
How do I edit the history data?

Running Reality allows editing the data that drives its history engine. The data is arranged into "worlds," each of which has a timeline. There are different kinds of timelines that have different requirements for data fidelity and for having citations to verify the data.

Learn about editing

Identifying and Reporting a Bug

I think I found a bug or an edit isn't working correctly. How do I report it?

The Running Reality team wants to hear from you and wants to fix any bugs that you find. We don't want software bugs, but they exist and we deploy app updates every few days to correct them. You can report bugs here:

Email the team

We will let you know we have received your bug report and let you know when it is fixed. We may ask for additional information to diagnose the problem, such as asking you to send a log file using the instructions below.

Finding the App's Files

How can I see the app's log files to diagnose problems?

Running Reality generates a log file every time it runs, recording major steps is is taking and any errors it might encounter. If you are helping tech support with hunting down a bug or problem, they may ask you to find these logs.

The simplest way to check the app's log files is to access them from the app's help menu:

The menu option to open the log files

When viewing the log files, you can also directly share them back to the Running Reality team. They may ask for a copy of the log to see the specific sequence of steps that led to your problem, and any error messages recorded along the way. The share button creates a new draft email on your computer to send the log to contribute@runningreality.org using your own default email app.

The button to click to share the log files

Note that if there is any personal information in the log file that you do not want shared, you may edit that out before sending the email. There is unlikely to be sensitive personal information in the log, but it may show your computer's file folder structure and therefore your user name. Running Reality won't use or share this information, but unencrypted emails could possibly be read while in transit by a third party.

The share button may give an error if you do not have a default email app configured in your operating system or if Running Reality does not have permission to send the email app a draft email. In this case, you can copy-paste the contents of the log file into a new, blank email, and send it to contribute@runningreality.org manually yourself.

The log files can also be found directly on your file system if you need to access them directly:

Where has the app itself been installed? I don't see it in Program Files or Applications?

Running Reality is installed into the following directories on your computer:



Feedback

If you can not find an answer here, please feel free to ask us for help. Send us an email if you would like us to get back to you with a response:

Email the team