From Jmol

Jump to: navigation, search


Reference: English – Other: 日本語 ·


Problems running the JSmol/HTML5 (non-Java) modality of the Jmol Object in a web page

Synchronous binary file transfer

An alert may be displayed on some pages, depending on the browser you use, saying

synchronous binary file transfer is requested but not available

This is harmless; you may disregard it as long as the page works (models are loaded). However, the success may depend on the browser being used. It is a warning for the page developer, who may disallow it in the page code using Jmol._alertNoBinary = false

Cached files

There are several levels of file caching in a typical web page with JSmol object.

  1. Caching the File icon.gif.html files.
  2. Caching the File icon.gif.js files --including the JSmol library files.
  3. Caching the model files (pdb, mol...) and script files that are loaded into JSmol by code in the page.

Clearing the browser cache is easy, although sometimes it takes several tries or closing and restarting the browser. But this will often solve just case #1, maybe #2.

If you change the version of JSmol library that is used by the page, it may prove harder to make the browser disregard the old files in cache. Consider that many js files making the JSmol library are not called directly by the webpage, but by other js files. So the browser may not be aware of them.

If you modify your js files, a common solution is to open the js file in the browser (type its url in the address line) and reload once or more until you see the changes being read. Then go back to the webpage and reload.

Getting rid of case #3 is harder. You may try the same approach: load and reload the pdb, mol or spt file directly in the browser, before reloading the page. This is not always possible since the browser will not display all kinds of files.

Generic tips

  • Find the procedure in your browser for clearing cache and for hard reload of a page, or install an extension that does that via a toolbar button, menu or key press.
  • Find if you can run your browser in a "disabled cache mode".

Clear cache in mobile Safari for iOS

  1. Go into Settings > Safari > Advanced > Website data > Remove all website data.
  2. Shut down Safari on phone, shut down the phone and start up again.

Problems running the Java modality of the Jmol Object in a web page

Jmol does not show up

First of all, wait. Java may take time to load the first time, and the Jmol applet must be downloaded. So, please wait for a while.

The web browser is not Java-compatible

Many current browsers do not support any longer the Java Plug-in needed to display applets like Jmol (Java modality). Among them: Google Chrome, Mozilla Firefox, Opera, Microsoft Edge.

Jmol is blocked by Java security

Applets in the browser may be blocked per Java security policies. In some situations, you just need to give permissions when a dialog requests to do so, but there are diverse setups and may be more difficult to solve.

You can find solutions in Installing and Enabling Java (Proteopedia wiki), which has step by step instructions for both Windows and Mac OS X, and for the 5 most popular web browsers.

As a general advice, if the Jmol applets are blocked in your browser you should try updating to the latest Java version from Oracle.

Yellow square with a message

  • Symptoms:

A yellow square is displayed in the place Jmol should go, with a message inside.

  • Solution:

Read the message. First, make sure that your web browser is one supporting the Java Plug-in (see above). If so, either you don't have Java installed, or the browser is configured not to use it. Try enabling Java for the browser or (re)install Java from Oracle's site.

If you are certain that you have Java installed, there is a chance that the problem is related to certain incompatibility between browser and Jmol versions; the fix is to update the Jmol version used by the page; read more.

Black square with an error

  • Symptoms:

A black square is displayed in the place Jmol should go, with a message inside: Error. Click to get more information. When you click, a dialog opens:

Application error.
The application could not execute.
Click on 'Details' for more information.

When you click, the Java console opens:

load: class JmolApplet not found.
java.lang.ClassNotFoundException: JmolApplet
  • Solution:

Check if you have forgotten to include a call to jmolInitialize() in your page's source code. Instructions for using jmolInitialize() and the Jmol.js library.

Jmol disappears in Internet Explorer 9

See Support/Windows#Jmol_pages_in_IE9

Jmol is displayed, but models are not

First of all, make sure you have set the paths correctly for the model files (paths should be relative to the html page; in special ocasions you may also work with absolute paths).

If models still fail to load, open the Java console (instructions) and look for errors. Most often, the cause is a Java security restriction (keep on reading below).

Java security errors

Java imposes a security policy on applets, designed to avoid web pages to act on your local disk. This implies some restrictions on what files can be opened by the Jmol applet.

The Java security errors related to this will have a format similar to:

FileManager opening file:sample.mol
script ERROR: script ERROR: io error reading file:sample.mol: 
access denied ( sample.mol read)

The rule of thumb is:

  • When the page is run from a local disk, Jmol applet can only open files (load models and scripts) that are in the same folder or below where the applet File icon.gif.jar files are.
See explanation and examples of allowed and disallowed folder layouts
  • When the page is run from a web server, Jmol applet can only open files that are in the same server.
However, recent Java versions may block access to files despite been in the same server. Particularly, script files invoked (from controls in the page) after the applet has loaded. If that happens, see the next section, The applet and model are displayed, but further actions have no effect, for a possible fix.
  • To overcome any of these limitations, you may use the signed applet, since that will request that the user explicitly gives permission beforehand and then there will be no limits for accessing files.

See also Unsigned vs. Signed Applet & Data Access.

Models do not load in a Mac

Pages run from a local disk in a Mac may fail due to Java security errors when you use Firefox or other Mozilla/Gecko browser. You should use Safari on MacOSX for local pages. On the web, Mozilla browsers do work fine.

Explanation: Mozilla browsers on the Mac are known to pass local paths as absolute paths through the JavaScript calls. This causes a Java security exception when running locally.

Models do not load in Linux

On Debian the Jmol application works fine, but the Jmol applet refuses to show the model.

A possible solution is to set net.ipv6.bindv6only=0 in File icon.gif/etc/sysctl.d/bindv6only.conf (maybe Debian only) and reboot.

Based on some information about a networking problem of Java.

Jmol and model are displayed, but further actions have no effect


  • The initial loading of model --and possibly a script-- works.
  • Further user-triggered actions, like clicking on buttons, links, menus etc. in the page, do not affect the model.
  • Java security error is displayed in the Java console, like this:
FileManager opening
ERROR in script: io error reading 
access denied ( connect,resolve)
eval ERROR: 
----line 1 command 1:
         script >> "example.spt" <<

This is a Java security limitation that only applies to recent Java versions. One solution is to use the signed applet. Another may be to set UseCommandThread.

Jmol is displayed, other problems

Popup menu does not open and server errors (Fedora)

  • Symptoms::

Everytime a page gets to the 'jmolApplet()' stage, the httpd logs give lots of errors like:

File does not exist: /var/www/html/jmol-11.8.25/org

Also, Jmol pop-up menu doesn't open and gives more of the same errors in the server log.

  • Solution:

It was a problem with the browser (Firefox 3.5.9 on Fedora 11): Firefox was using the OpenJDK runtime environment and the associated IcedTea plugin. Installing Sun's Java and its plugin fixed the problem.


OpenJDK Java must be removed (yum whatprovides java will show you the precise versions to uninstall):

> sudo yum remove java-1.6.0-openjdk-plugin-
> sudo yum remove java-1.6.0-openjdk-

Then add the new plugin (the precise file to link may differ):

> cd ~/.mozilla
> mkdir plugins
> cd plugins
> ln -s /usr/java/jdk1.6.0_16/jre/plugin/i386/ns7/

Then open Firefox, select Tools > Addons, and enable the Java plug-in.

Jmol does not respond to controls in page (Mac Safari)

This has been reported in Safari 5.0.1 on Mac OS X 10.6.4.

  • The page loads but the applet bails (literally the message bar says the applet bailed)
  • The applet loads but clicking on a link that should act on the applet does nthing. Safari may even crash.

The problem was tracked down to the AdBlock extension in Safari. Disabling the extension removes the problem.

Extracting information from the Jmol applet

Remember that the unsigned applet cannot read from or write to the local disk. Therefore, file operations are excluded; output cannot go to disk, only to the Script Console and/or the Java Console.

Copying code from the script console

Recent versions of Java (at least 1.6.0_25 and later) prevent text output to Jmol Script Console to be copied and then pasted outside Java.

Possible workarounds for this:

  • Some output from Jmol is also displayed in the Java Console. From there, you can copy and then paste outside.
  • Select the text in the Script Console and, rather than copying it, drag and drop to a text editor.

See also Copying_and_pasting_scripts.

Personal tools