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.

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:

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. 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 meet Apple's stringent app notarization requirements which means that Apple has checked and certified the safety of each version of 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."

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.

• MacOS: look in your Downloads folder for our .DMG file.
• Windows: look in your Downloads folder for our .EXE file.
• Linux: look in your ~ home directory for our .TAR file.

The system requirements are below:

• A laptop or desktop computer
• We use Java 21 or higher, but don't require you to have it installed already.
• 4Gb system RAM minimum, 8Gb to run well.
• 600Mb free hard drive space (slightly more may be needed during app installation up to 850Mb)
• Web Browser installed: Firefox, Edge, Safari, or Chrome
• Operating System: MacOS, Windows, or Linux

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.

This means that the installer failed to install all the parts of the app and a part is missing. This can happen when the network is interrupted during the upload or download of the installer.

To fix this problem, you must un-install the app and then re-install it fresh from the app downloads page. We suggest doing a fresh download of the installer and not re-using any already downloaded installer that may have been interrupted, including either a prior fresh installer or an "update" installer. You must un-install the app first because the app will appear to the Operating System and any "update" installer to be completely installed but is missing just a single part.

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 and notarized by Apple with an identified developer certificate.

• Open the System Preferences
• Go to Security & Privacy
• Allow apps from App Store and identified developers
• (You may have to click the lock button at the bottom to allow changes.)

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:

• Your antivirus software is blocking Running Reality. If this is the problem, you should also be seeing a warning from that software.
• You have a character in your username that is beyond the 26 letters of the western alphabet. If you install the software in a directory other than your home directory, it should run normally.
• You do not have at least 4Gb of RAM installed on your computer or you do not have at least a 2Gb block of free memory available to start the app.

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:

• Have Running Reality open in your device's web browser.
• Click the "Share" button in the middle of the toolbar at the bottom of the screen.
• Scroll down and click the "Add to home screen" button near the bottom of the list of share options.
  
• Running Reality is now available on your device home screen.

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:

• Have Running Reality open in your device's web browser.
• Click the "Add to Home Screen" button in the header.
• On some versions of the Chrome browser for Android, you have to visit a website at least twice, with visits spaced more than 5 minutes apart, before the button appears in the header.
• Running Reality is now available on your device home screen.

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. This happens to everyone once, sometimes after a cat bumps into your mouse wheel.

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

The app installs the low-resolution map by default, then deeper zooms require downloading the additional map tiles. Until those tiles have loaded, the app may show just basic blue tiles. You may consider installing the optional deeper map tile component during installation if you plan to use Running Reality offline or in a place with low bandwidth, so that deeper zoom tiles are pre-downloaded.

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.

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.

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.

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:

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.

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:

• MacOS: ~/Documents/RunningReality/logs
• Windows: C:\Users\[Your name]\Documents\RunningReality\logs
• Linux: ~/RunningReality/logs

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:

• MacOS: /Applications/RunningReality.app
• Windows: C:\Program Files\RunningReality
• Linux: ~/RunningReality

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