General notes on the Java virtual machine and memory parameters
Trader Workstation is a Java-based application. Programs which are compiled using Java execute within a Java virtual machine (JVM) process which manages the interactions between the program, and the operating system and hardware. The Java virtual machine dynamically manages the memory usage for the program running in it. There are many technical aspects to how the memory is managed, but there are two primary spaces or blocks of memory which are of concern for running the TWS: the heap space, and the permanent generation (permgen) space.
The heap is the area in memory where all class instances and arrays are allocated. The heap is created when the JVM is started, and space is periodically reclaimed by the garbage collector (GC), the Java Virtual Machine's automatic storage management system. There is also non-heap space, known as the permanent generation space, utilized by the Java Virtual Machine to hold code which typically has a longer life in memory, or a specific usage. If either of these spaces are not sized correctly, errors can occur when the process runs out of memory in these spaces. If this occurs, the program will appear to be frozen or may crash completely, and the log files in the program directory for TWS (in C:\Jts, by default on Windows OS) will likely include one of the following errors:
java.lang.OutOfMemoryError: Java heap space
java.lang.OutOfMemoryError: PermGen space
When launching a Java program, it is possible to pass certain parameters to the Java virtual machine to adjust how much memory the process will use to run the program. The
Xmx flag controls the maximum amount of memory to be used for the heap space, and the
XX:MaxPermSize flag controls the maximum amount of memory to be used for the permanent generation space.
As we have released newer versions of TWS which contain more features, the memory required for the Java virtual machine to effectively run TWS has increased.
The above are the bare minimums necessary to run the program for most customers. Usage of many of the features in TWS will require higher memory allotments.
Some users may have old shortcuts or use custom scripts to launch TWS. It is crucial that these are updated accordingly to use at least the minimum memory parameters mentioned above. Some users who have extensive portfolios or execute large amount of orders may need to adjust the parameters to improve performance. The heap size can be increased if there is an
OutOfMemoryError pertaining to the heap space. Note, in our experience the memory should typically not need to be increased above 1024M in the heap and 256M in the permgen.
If at any time following adjusting the memory parameters, you receive an error that the system could not create the Java Virtual Machine, this indicates the memory increase was too aggressive, and you need to scale back the parameters.
**Please note the following: Starting with Java 8, the
XX:MaxPermSize parameter has been deprecated. When running TWS with Java 8, the
XX:MaxPermSize parameter will be ignored at runtime if present; this parameter could be simply omitted from the start-up script.
Browser-based TWS (Java WebStart version)
IB uses a script on our website to dynamically serve a JNLP file with different memory parameters based on the URL request from the browser. When launching TWS from our website, you can add the
Xmps parameters to the URL to configure the heap size and and permanent generation space size, respectively for the Java virtual machine process which will run TWS. For example:
will result in a JNLP file with the max heap size set to 768 mb and the max permanent generation space size set to 128MB.
If you encountered a resource allocation message when launching a previously saved copy of the JNLP file, and were directed to this webpage, please download a new version of the JNLP file from here. The file you are using is likely out-of-date, and does not contain the correct resource allocation parameters for your operating system.
Standalone TWS on Windows
To adjust the memory parameters used when launching TWS from the desktop or start menu shortcut:
XX:MaxPermSizeflags in the target field
Standalone TWS on Mac
To adjust the memory parameters used when launching TWS using the Trader_Workstation_X.app icon:
XX:MaxPermSizeflags, and adjust the values following the flags to the desired size
Standalone TWS on UNIX (or Mac) via terminal command
When executing the command to start TWS from the terminal, adjust the values following the
XX:MaxPermSize flags to the desired size. For example, if you would normally launch using:
java -cp jts.jar:total.2013.jar -Xmx512M -XX:MaxPermSize=128M jclient.LoginFrame
but need to increase due to errors or freezing due to running out of memory, you can instead run:
java -cp jts.jar:total.2013.jar -Xmx768M -XX:MaxPermSize=256M jclient.LoginFrame
Account holders receiving the following message Order Barriers are supported only for CCP-simulated stops are attempting to enter an order that has attributes that are not supported and must be modified before the order can be accepted.
An order barrier is a setting (i.e. condition) associated with an order that says, when this barrier is reached trigger an order action. The order action may be triggering a trailing mit, or it may be changing the order type as with an adjustable stop. Exchanges do not support certain order types that contain barriers which are available in the TWS. When this is the case, IB will generally simulate these orders (ie: send only the order details to the exchange that they support and internally handle any order barriers that are not recognized by the exchange.)
Orders that cannot be simulated can only be configured with order barriers that are supported by that exchange. If a native order type is submitted with a barrier not supported by the exhange it will be rejected.
Please notify customer service of any such rejections through a web ticket so that we are able to review the details of the order being submitted and ensure that the issue is known. Please include the following information in the ticket so that we are able to identify the specific order in question;
Additional information regarding how to submit a Web Ticket can be found here.
Account holders receiving the following message "At the moment, orders for this contract are only accepted if they close or reduce open positions. Please contact customer service for assistance" will not be able to place orders that would open or increase positions in the specific security.
This restriction, referred to as a closing only restriction, may be applied for a number of reasons including the following;
Traders may request that the trading restriction be removed from the security in question by submitting a web ticket with the following information;
Once received, IB will review the request and determine whether or not removal of the restriction can be facilitated.
Additional information regarding how to submit a Web Ticket can be found here.
Account holders receiving the message Order price is not reasonable will have to modify the price associated with the order before it will be successfully submitted.
Account holders receiving the message Cannot verify reasonableness of order will have the option of overriding the message and transmitting the order.
The basis for the order reasonability rejections may vary but are all related to the order price relative to the current market. These reject messages are implemented as precautionary and are intended to prevent orders from being executed based on erroneous price submissions. Some scenarios that may cause these types of rejections are as follows;
Account holders receiving the message could not value contract at this time will be unable to successfully transmit an order for the product in question.
The basis for the rejection varies, however, all potential issues causing this are related to an inability of our automated systems to accurately determine a value for the contract based on real time data and credit management. Some scenarios that may cause this type of rejection are as follows;
Account holders receiving the following message 'Your account is restricted from placing orders at this time' are not allowed to place any opening or closing orders without prior assistance from the IB Trade Desk. Questions regarding this restriction should be addressed to the Trade Desk via Customer Service (see contact information link below).
Account holders receiving the following message 'Your account has been restricted to placing closing orders only' are limited to placing orders which serve to close or reduce existing positions (i.e., sell orders which close out or reduce existing long positions or buy orders which which close out or reduce existing short positions). The basis for this restriction varies and often involves pending documentation, compliance and/or risk issues. Regardless of its basis, the restriction affords account holders the ability to manage and reduce the market exposure of their positions while in effect. Questions regarding this restriction should be addressed to Customer Service (see contact information link below).
Order types which provide privacy by either hiding the entire order quantity (i.e., Hidden Orders) or allowing the display of only a specified portion of the submitted order quantity (i.e., Iceberg/Reserves) are not supported for all product types and venues.
Examples of venues for which Hidden and Iceberg/Reserve stock orders are not supported are Pink Sheet and OTCBB. Hidden or Iceberg/Reserve orders submitted to these venues will be rejected and will generate the following message: "Order quantity must be fully displayed for this instrument". Orders receiving this rejection message will require the removal of any hidden or display size attribute prior to resubmission.
Additional information regarding product types and venues for which these order types are supported is available through the links below:
Traders may only have 3 volatility based orders active in a single account at any given time.
Additional information regarding volatility orders can be found here.
The message "limit on concurrent pegged-to-stock and volatility orders exceeded" will appear when a trader has 3 working volatility orders and attempts to place a 4th. When this message appears, the first three submitted orders will not be affected and the 4th order will be rejected.
Traders may choose to cancel one of the three working orders in their account in order to be able to submit a new volatility order. The working quantity limitation cannot be overridden.
Back to TWS Rejection Messages
This message refers to orders which are transmitted that violate parameters established by the account holder through the configurable settings in the TWS. The account holder is able to establish Precautionary Settings in the TWS by navigating to the Order >> Configure Order Presets menu.
Note that this setting does not prevent orders from being submitted but rather controls when a warning message will appear indicating that the precautionary setting has been penetrated. Traders have the option to acknowledge this message and submit the order.
The Order >> Configure Order Presets menu will open up a window providing for the creation of price thresholds set in terms of percentage or the number of ticks outside of the NBBO (settings may also be defined in terms of share/contract quantity or total dollar value of trade). When an order violating the account holder's parameters is transmitted, it will be rejected and a TWS pop-up window will be displayed with the following warning message: "The price specified would violate the percentage constraint specified in the default order settings. Do you really want to submit this order".
Traders may click Yes to override this warning and submit the order or No to cancel it.
Back to TWS Rejection Messages