While working with Fiorano platform, at some occasion, you may encounter certain unforeseen issues. Following are a few issues and their solutions/workarounds, which help you work seamlessly:


Setting the hostname 

Frequently one encounters the following types of errors when the correct hostname is not set on the machine.

1: Error caused by java.net.UnknownHostException: SERVER2-SOAServer02: SERVER2-SOAServer02
2.1: Error occured when the correct hostname is not set in the FES machine and FPS is started

While the error above can be seen on the console, if the user checks the esberr.log file of the peer server in runtime data, the following error can be seen:

2.2: Error displayed in the esberr.log file when the correct hostname is not set in the FES machine and FPS is started
3: Error occured while adding Breakpoint from eStudio



Check whether hostname -i command in the terminal / command prompt gives the correct in-use IP address of the host, if it does not, you need to modify the hosts file.

The hosts file is used by the operating system to map hostnames to IP addresses. To set the hostname, one needs to modify the hosts file which contains lines of text consisting of an IP address in the first text field followed by one or more host names. Follow the steps below to modify the file.

For Linux

To edit the hosts file present in the etc folder, perform the following actions:

  1. To open the /etc/hosts file, open the terminal, switch to superuser and use the command:

  2. In the hosts file that gets opened, locate your old hostname, which resembles one of the below lines:
    1. <ip_address> <your-old-hostname> <your-old-hostname>.<domain>
    2. <ip_address> <your-old-hostname>
  3. Replace the old hostname with the correct hostname and save the hosts file.
  4. In the terminal, type the following:

  5. To see if the hostname has been set properly, use the following command:

For windows

The hosts file is present in C:\Windows\System32\Drivers\etc\hosts. To modify this, perform the following actions:

  1. Do any of the following to execute Run command:
    1. Go to Start > Run
    2. Press Windows key + R
  2. Open the hosts file present at C:\Windows\System32\Drivers\etc in a notepad using the command:


    User should have administrative rights to edit the hosts file.

  3. In the hosts file that gets opened, locate your old hostname which resembles one of the below lines:
    1. <ip_address> <your-old-hostname> <your-old-hostname>.<domain>
    2. <ip_address> <your-old-hostname>
  4. Replace the old hostname with your correct hostname.
  5. Now that hosts have been edited, save the file.

To change the computer name, if required, perform the following actions:

  1. Click on the Start button, right-click Computer, and then select Properties option.
  2. Under the Computer name tab click Change settings button.
  3. In the Computer description text field,  type the correct hostname, and then click OK. If the computer is part of a domain,  provide the name and password of an account that has permission to rename the computer in the domain.
  4. Restart the system once it prompts to do so.
  5. After it restarts, to check the hostname,

    1. open command prompt by going to Start > Run and Enter "cmd".

    2. check the hostname by executing the following command:

Peer on Multi-homed machine

If the Peer server is started on a multi-homed machine, and launching EventProcesses is taking a lot of time, throwing timeout exceptions at times, then configure MQ address (working) for the peer as follows:

  1. Open FPS profile in Fiorano eStudio
  2. Navigate through Fiorano > socketAcceptors > ConnectionManager
  3. Set the ServerAddress property to the desired IP Address.


Firewall Issues

If a host running the server has a firewall, which only allows connections on some specific ports, the firewall has to be modified to allow connections from other ports.
If the host running the server is a multi-homed host and creating routes or breakpoints is causing problems, check if the connect URL of the server connection factories point to the IP address which is firewalled/barred from accepting connections.

  • If creating routes is causing issues,
    • Login to eStudio > ConnectionManagement > FES
    • Change connectURL of peer connection factories to the correct one if they point to a firewalled IP.
  • If creating breakpoints is causing issues,
    • Login to eStudio > ConnectionManagement > FES
    • Change connectURL of PRIMARYQCF, SERVICEPROVIDERQCF, CF, TCF to the correct one if they point to a firewalled IP.


eStudio login issue

If login to a server on remote machine is extremely slow, seeming like it is hung, check if Windows firewall is ON in the eStudio machine and disable it.

File encoding issue

When working with locales other than English, it is recommended to set the encoding property while working with mappings.

  • Add the following in %FIORANO_HOME%/eStudio/eStudio.ini

  • Navigate through eStudio > Window > Preferences > Fiorano > SOA Orchestration > CPS Launch (Tab) > System Properties and add file.encoding as name and UTF-8 as Value.
  • Add file.encoding=UTF-8 at <java.system.props> in %FIORANO_HOME%/esb/fes/bin/fes.conf.


    In case of multiple esb/fes servers, repeat this step for all esb/fes servers.

  • Add file.encoding=UTF-8 at <java.system.props> in %FIORANO_HOME%/esb/fps/bin/fps.conf.


    In case of multiple peer/fps servers, repeat this step for all peer/fps servers.

  • If required, other encodings can also be used in place of UTF-8.
  • If multi-byte characters are already used in mapper funclets (as constants), existing mappings or characters may get deleted or corrupted because of differences in encoding. Redrawing mappings is recommended in this scenario.

Client Connections in Peer

If the following error occurs, then increase Client Connections in Peer:

  1. Open FPS profile in eStudio.
  2. Navigate through Fiorano > socketAcceptors > ConnectionManager.
  3. Set the MaxClientConnectionsCount property to a value higher than 1024.


File Handles in Linux

If the following error is encountered, increase the system file handles:

Open the file limits.conf present at the location /etc/security and add the following lines at the end of the content:

  • soft      nofile    <noOfFileHandles>
  • hard     nofile    <noOfFileHandles>


Problems when Non-ascii Chars used in build.properties

If user is running CLI tools on Linux and the Applications/Services names contain non-ascii characters, the process may fail.

To resolve,

  1. Perform any one of the following
    1. either convert the file into unicode
      • native2ascii build.properties > newbuild.properties
    2. reconvert into ISO8859-1
      • iconv -f UTF-8 -t ISO8859-1 build.properties > newbuild.properties.
  2. Use the new build.properties file for CLI tasks.


JRE Problems

If the following error is observed on running the Fiorano servers, if a JRE(at <JRE PATH>) other than one shipped, either use corresponding JDK or copy the JDK's jre\bin\server folder to <JRE PATH>\bin\server directory.


For more information, please refer to the following link:



HA Troubleshooting

  1. SocketBindException saying that the HA Port is already bound
    This exception indicates that some other program that is running on the HA port or the last instance of the server is not properly killed.
    Stop/kill the application which is holding up the port and start the server again or choose a different HA port. But changing this means that there needs to be a change in the Backup Servers' configuration for its Backup Server port.
  2. None of the servers starting up
    Both the servers are in WAITING state and the Primary Server is trying to connect to its Backup Server.
    This exception indicates that the Backup Server IP and port numbers are wrong for both the server configurations.

    Example: Server console when it cannot connect to the Backup Server.

    The figure below illustrates a situation where the server is not able to connect to the Backup Server. If it is already connected, then there is a problem with the configuration. The message prints the IP address and the port to which it is trying to connect to establish the HA channel.
    Check if the Backup Server is running in the printed IP address and port.

    Figure 1: Server unable to connect to the Backup Server
  3. One of the HA Servers switched into Active or Passive Sync and it hangs there, but the other seems to be in WAITING state for a long time trying to connect to the Backup Server.
    This exception indicates that your configuration for the Backup Servers does not match at the end where the server is still in WAITING state, but the Backup Server is still able to connect. This will cause the Backup Server to hand indefinitely as it expects a Synchronization Complete Notification which is never going to be delivered.

    Figure 2: The server hanging in one of the synchronization states
  4. Both servers go to Standalone/Active state in replicated/shared mode respectively if the network link between them is broken.
    This can happen if the servers do not refer to the same LockFile.
  5. The server in replicated mode shuts down on boot up
    This can happen if the LockFile specified is not valid or the machine hosting the LockFile is not allowing the server to acquire a lock. Figure 3 illustrates the server shutting down on boot up.

    Figure 3: The server shutting down on boot up 

Handling "Client ID Already Exists" exception

This error can occur when FES is force closed when the break points are in place or when break point addition fails due to any other reason on previous attempt. In such a case the client corresponding to the previous connection needs to be removed. Follow the steps below and add the break point again.

Identifying the Connection 

  1. Login to ESB Dashboard. Under the Server Status node, select the Enterprise Server and then Select Connections. 
  2. Check for PTP connections related to unclosed break points. The connection names will have the pattern <CLIENT_ID>,<Number> .


    Client IDs will be of the format ESBX_SYSTEM<Event Process Name><Version><RouteName>C and ESBXSYSTEM<EventProcessName><Version><COMPONENT_NAME>_<RouteName>

  3. Copy the ClientIDs from here.

Closing Identified Connections


All the operations outlined have to be performed in connection management perspective of eStudio.

  1. Log into FES-JMX and navigate to Admin Service node as shown below

  2. Right-click on the node and click – ViewOperations which opens the dialog as shown below

  3. Choose the operation disconnectClient(clientID) and provide the clientIDs from the above section.
  4. Click on the disconnectClient button, a value true will be seen in the Result Tab and the client will get disconnected. 

You can verify this by refreshing the dashboard list of connections found in the above section.

Adaptavist ThemeBuilder EngineAtlassian Confluence