Troubleshooting

This page covers common issues you may encounter when running ioBufferPro and how to resolve them. If you cannot find a solution here, see the Getting Help section at the bottom of this page.

Startup Issues

If ioBufferPro starts and immediately stops (or fails to start at all), follow these steps to identify the problem.

Step 1: Check for Known Error Messages

Start ioBufferPro directly from the command line to see the full error output:

ioBufferPro.exe

Look for one of these common messages in the output:

• FileNotFoundError — A required file or directory is missing. Verify that all files were extracted correctly.
• PermissionError — ioBufferPro does not have permission to read or write a required file. Check directory permissions, especially for data/ and logs/.
• Missing DLL errors — A required system library is missing or the installation is corrupted. Try re-extracting or reinstalling ioBufferPro.

Step 2: Check the Log File

If ioBufferPro started briefly before stopping, there may be useful information in the log file:

logs/ipbuffer.log

Review the most recent entries for error messages or warnings that indicate what went wrong.

TIP

If the logs/ directory does not exist, ioBufferPro may not have had a chance to create it. Try creating it manually and restarting.

Common Errors

The table below summarizes the most frequently encountered errors and their solutions.

Problem	Cause	Solution
Port already in use	Another application is using port 8080 or 8081	Check with netstat -ano | findstr "8080" (Windows) or lsof -i :8080 (Linux/macOS), then change the port in your config or stop the conflicting application
Database initialization fails	Missing data/ directory or insufficient permissions	Verify that the data/ directory exists and is writable, and check that you have sufficient disk space
Missing DLL errors	Corrupted or incomplete installation	Re-extract or reinstall ioBufferPro. Ensure all files from the distribution package are present in the installation directory

Channel Issues

Channel Won't Start

If a channel fails to start:

1. Open the Management Dashboard and check System Logs for error messages related to the channel.
2. Verify that the ports configured for the channel are available and not in use by another application.
3. Check your firewall rules to ensure inbound and outbound traffic is allowed on the configured ports.

No Messages Appearing

If a channel is running but no messages are being received:

1. Verify that the channel status shows Started in the dashboard.
2. Confirm that the connection indicator shows green (connected). A red or yellow indicator means the connection is not established.
3. Verify that the external system (PLC, SCADA, or other application) is actively sending messages to the correct address and port.

Connection Failures by Type

Different connection types have different failure modes. Use the guidance below based on your channel's connection type.

TCP Client:

• Verify that the remote server is running and reachable from the ioBufferPro host.
• Test connectivity with ping or telnet to confirm the remote address and port are accessible.

TCP Server:

• Check that your firewall allows inbound connections on the configured port.
• Verify that no other application is already listening on the same port.

Serial (RS232/RS485):

• Verify that the correct COM port is selected in the channel configuration.
• Confirm that the baud rate, data bits, stop bits, and parity settings match the connected device.
• Check that the serial cable is securely connected and that the correct cable type is being used (straight-through vs. crossover).

Remote ioBufferPro:

• Verify that the remote ioBufferPro URL is correct and reachable.
• Confirm that the credentials (username and password) are valid on the remote instance.
• Check that network connectivity between the two ioBufferPro instances is stable.

WARNING

Serial connection issues are often caused by mismatched communication parameters. Double-check that the baud rate, data bits, stop bits, and parity settings in ioBufferPro exactly match the settings on the connected device.

Performance Issues

Slow Performance on Raspberry Pi

If ioBufferPro runs slowly on a Raspberry Pi, the most common cause is using an SD card for storage. SQLite write performance on SD cards can be up to 60x slower than on an SSD.

Solution: Use a USB-connected SSD instead of an SD card. Enable USB boot in raspi-config for best performance.

High Database Write Times

If the dashboard shows high database write times:

1. Check the health of your storage device (SSD or hard drive). Failing disks can cause significant write slowdowns.
2. Verify that the disk is not full or nearly full. SQLite needs free space to operate efficiently.
3. Consider upgrading to an SSD if you are currently using a traditional hard drive or SD card.

High Memory Usage

If ioBufferPro is consuming more memory than expected:

1. Review the number of active channels. Each channel maintains its own message buffer in memory.
2. Check for large message backlogs. If messages are being buffered faster than they can be delivered, the buffer will grow and consume more memory.
3. Investigate whether the destination system is down or slow, causing messages to accumulate.

TIP

You can monitor memory usage, buffer depth, and database performance in real time from the Management Dashboard on port 8081.

License Issues

License Won't Activate

If online license activation fails:

1. Verify that the ioBufferPro host has an active internet connection.
2. Confirm that the license key is entered correctly, with no extra spaces or missing characters.
3. Check that the license key has not expired. Expired keys must be renewed before activation.

Offline License Not Found

If you are using offline licensing and ioBufferPro reports that no license was found:

1. Verify that the license.lic file is placed in the correct location within your ioBufferPro installation directory.
2. Ensure the file is named exactly license.lic and is placed in the root of the ioBufferPro directory.

Machine-Locked License Fails

If a machine-locked license is not being accepted:

1. Verify that the hardware fingerprint of the current machine matches the one the license was issued for.
2. Confirm that the license file was not copied from a different machine. Machine-locked licenses are tied to specific hardware.

DANGER

Machine-locked licenses cannot be transferred between devices. If you need to move ioBufferPro to new hardware, contact support to have your license reissued.

Trial Expired

If your trial period has ended, ioBufferPro will no longer start. To continue using ioBufferPro, upgrade to a paid plan via the ioBufferPro website.

Advanced Diagnostics

Use the commands below to perform deeper troubleshooting when the standard steps do not resolve your issue.

Check If Ports Are Available

Verify that the ports ioBufferPro needs (8080 and 8081 by default) are not in use by another application.

Windows:

netstat -ano | findstr "8080"
netstat -ano | findstr "8081"

Linux/macOS:

lsof -i :8080
lsof -i :8081

If either command returns output, another application is using that port. Either stop the conflicting application or change the ioBufferPro port in your configuration file.

Verify Database Health

If you suspect database issues, use the built-in health check:

ioBufferPro.exe --health-check

This verifies database integrity along with other system checks. If the health check reports problems with the database, restore from a backup or contact support for assistance.

WARNING

If the health check reports database corruption, do not continue running ioBufferPro with the damaged database. Restore from a backup or contact support for assistance.

Environment-Specific Issues

Windows Firewall

Windows Firewall may block ioBufferPro from accepting network connections. When you first start ioBufferPro, Windows may display a firewall prompt asking whether to allow the application.

Solution: Click Allow access when prompted. If you dismissed the prompt, you can manually add a firewall exception through Windows Security > Firewall & network protection > Allow an app through firewall.

Antivirus Software

Some antivirus programs may flag or quarantine ioBufferPro, especially if it opens network ports or accesses system resources.

Solution: Add an exception for the ioBufferPro installation directory in your antivirus software. Refer to your antivirus documentation for instructions on adding folder exclusions.

TIP

If ioBufferPro was working and suddenly stops after an antivirus update, check your antivirus quarantine log. The antivirus may have removed or blocked a required file.

Virtual Machines

When running ioBufferPro inside a virtual machine:

1. Ensure that the VM's network adapter is properly configured (bridged or NAT, depending on your needs).
2. Verify that the VM's IP address is accessible from your network if external systems need to connect to ioBufferPro.
3. Check that the VM host is not blocking traffic to/from the guest on the required ports.

Getting Help

If you have worked through the troubleshooting steps above and are still experiencing issues, contact support with the following information to help us resolve your problem quickly:

1. Full error message — Run ioBufferPro directly from the command line and capture the complete error output:

   ioBufferPro.exe

2. Log file contents — Include the contents of logs/ipbuffer.log (if the file exists).

3. Operating system and version — For example, Windows 11 Pro, Ubuntu 22.04, or Raspberry Pi OS Bookworm.

4. ioBufferPro version — Include the version of ioBufferPro you are running (found in the Management Dashboard or the application's About dialog).

TIP

The more information you provide upfront, the faster we can diagnose and resolve your issue. Including all four items above with your initial support request will help avoid back-and-forth delays.