Troubleshooting Reference

Comprehensive troubleshooting guide for FrameworX solutions, covering common issues, diagnostics, and recovery procedures.

Platform | Installation | Solution | Modules | Controls | Code | Troubleshooting

Quick Diagnostics Checklist

Initial Verification

• Services running (TWebServices, TServer)
• Network connectivity verified
• Firewall ports open (10108, 3101, solution-specific)
• License validated (including Runtime Clients)
• Guest user permissions configured
• Database connection established
• Client access working

Diagnostic Flow

1. Identify symptoms
2. Check logs (Event Viewer, TraceLogs)
3. Run diagnostics (/SaveLog:3)
4. Apply solution
5. Verify fix
6. Document resolution

Startup Problems

Runtime Won't Start

Symptoms:

• Service fails to start
• Error message on startup
• Runtime crashes immediately
• No response from server

Diagnostics:

cmd

# Check service status
sc query "TStartup-<SolutionName>"

# Review Windows Event Log
eventvwr.msc

# Check startup log
type "C:\Users\Public\Documents\FrameworX\TraceLogs\*.log"

Common Causes and Solutions:

Detailed Resolution Steps:

1. Check Database Connection
   • Test connection string in Designer
   • Verify SQL Server TCP/IP is enabled
   • Check firewall rules for port 1433
   • Test with SQL Management Studio
2. Resolve Port Conflicts

   cmd

   netstat -ano | findstr :3101
   tasklist | findstr [PID]

3. Verify License
   • Check Runtime → License tab
   • Ensure license is active
   • Verify expiration date

Designer Won't Open

Symptoms:

• Designer crashes on launch
• Blank screen or frozen interface
• Error loading solution
• Missing menus or toolbars

Resolution Matrix:

Connection Issues

Device Communication Failures

Symptoms:

• Tags showing bad quality
• No data from devices
• Intermittent communication
• High error counts

Diagnostic Steps:

1. Check Device Status
   • Designer → Devices → Runtime Status
   • Review error counts and last response time
2. Test Communication

   cmd

   ping [device-ip]
   telnet [device-ip] [port]

3. Review Configuration
   • Verify IP address and port
   • Check device addressing
   • Confirm protocol settings

Common Issues by Protocol:

Web Client Connection Checklist

1. Verify Server Process

cmd

# Check if TServer.exe is running
tasklist | findstr TServer

# Verify port (default 3101)
netstat -aon | findstr :3101

2. Check Guest User Permissions

Navigate to Security → Permissions:

• Verify GUEST user has "CLIENT START" or unrestricted access
• Guest user should be in GUEST group by default

3. Verify License

Runtime → License tab:

• Check "Runtime Web Clients" ≥ 1
• Verify license is active

4. Test Local Connection First

http://localhost:3101/html5
http://127.0.0.1:3101/smartclient

5. Network Diagnostics

cmd

# Test connectivity
ping server-ip

# Test port
telnet server-ip 3101

# Trace route
tracert server-ip

# Check firewall
netsh advfirewall firewall show rule name=all | findstr 3101

Smart Client Issues

Microsoft Blocks Download

Symptom: "Not a verified Microsoft application" warning

Solution:

1. Windows Settings → Apps & features
2. Under "Choose where to get apps"
3. Change from "Microsoft Store only" to "Anywhere"

FIPS Compliance Error

Solution:

1. Run gpedit.msc as Administrator
2. Computer Configuration → Windows Settings → Security Settings → Local Policies → Security Options
3. Set "System Cryptography: Use FIPS compliant algorithms" to Disabled

For Windows 10 Home (no gpedit.msc):

batch

@echo off
pushd "%~dp0"
dir /b C:\Windows\servicing\Packages\Microsoft-Windows-GroupPolicy-ClientExtensions-Package~3*.mum >List.txt
dir /b C:\Windows\servicing\Packages\Microsoft-Windows-GroupPolicy-ClientTools-Package~3*.mum >>List.txt
for /f %%i in ('findstr /i . List.txt 2^>nul') do dism /online /norestart /add-package:"C:\Windows\servicing\Packages\%%i"
pause

Performance Issues

High CPU Usage

Symptoms:

• CPU constantly above 80%
• System sluggish
• Client updates slow
• Delays in processing

Performance Analysis:

powershell

# Monitor process
Get-Process TStartup, TServer, TWebServices | Select Name, CPU, @{n='RAM(MB)';e={$_.WS/1MB}}

# Check thread count
Get-Process TServer | Select Threads, Handles

Common Causes:

Memory Leaks

Symptoms:

• Memory usage growing continuously
• Out of memory errors
• Performance degradation over time

Common Memory Issues:

Performance Baselines

Data Issues

Tags Not Updating

Diagnostic Flow:

Check Device Communication
    ↓ OK
Check Point Mapping
    ↓ OK
Check Tag Configuration
    ↓ OK
Check Security Permissions
    ↓ OK
Check Runtime Status

Tag Diagnostics:

1. Use Property Watch to monitor value, quality, timestamp
2. Enable Tag Trace: Designer → Tools → Diagnostics → Tag Trace

Historian Data Gaps

Alarm Issues

Alarm Flooding

Identify Chattering Alarms:

sql

SELECT Tag, COUNT(*) as Count
FROM AlarmHistory
WHERE Timestamp > DATEADD(hour, -1, GETDATE())
GROUP BY Tag
ORDER BY Count DESC

Remediation:

• Add deadband to analog alarms
• Increase delay timers
• Implement alarm shelving
• Filter nuisance alarms

Notification Issues

Email Troubleshooting:

1. Test SMTP: Designer → Alarms → Notification → Test Email
2. Verify:
   • SMTP server address
   • Port (25, 587, 465)
   • Authentication credentials
   • TLS/SSL settings
   • From address validity

Error Code Reference

Runtime Errors (FX-1xxx)

Communication Errors (FX-2xxx)

Database Errors (FX-3xxx)

Diagnostic Tools

Built-in Diagnostics

Runtime Information Monitor

• Access: Solution Center → Tools → Runtime Info
• Shows: Module status, memory, threads, connections

Communication Trace

• Access: Designer → Tools → Communication Trace
• Shows: Protocol messages, timing, errors

Log Analyzer

• Access: Solution Center → Tools → Log Analyzer
• Features: Filter by severity, search, export

Enable Verbose Logging

cmd

TStartup.exe /Solution:"C:\Solutions\MySolution.dbsln" 
  /SaveLog:3 
  /AutoRunDiagnostics:30 
  /LogDeviceWriteStartup

External Tools

powershell

# Check service status
Get-Service -Name "TStartup-*", "TWebServices", "FrameworX*"

# Monitor process
Get-Process TStartup, TServer, TWebServices | Select CPU, WS, Handles

# Check network connections
Get-NetTCPConnection -LocalPort 3101

# Review event logs
Get-EventLog -LogName Application -Source "TStartup*" -Newest 50

Recovery Procedures

Solution File Backup and Restore

A solution is a single SQLite file with the .dbsln extension. To back it up, copy the file while Designer and the runtime are closed, or use Export ZIP on the Solution Export page (see Solution Export Reference). To restore, close Designer and the runtime, then replace the file with the copy.

To check a solution file for damage, run the SQLite integrity check on a copy of the file:

sqlite3 "C:\Backup\MySolution.dbsln" "PRAGMA integrity_check;"

Historian and alarm data kept on SQL Server or another external database are backed up and repaired with that database server's own tools, on the database the solution's storage location points to.

Solution Recovery

1. Close Designer and the runtime.
2. Restore the latest copy of the .dbsln file, or the solution from the latest ZIP export.
3. If the solution is tracked with Git export, its JSON files hold the configuration. See Git Integration and Export Reference.
4. Open the restored solution in Designer and test it before returning it to production.

Start with Fewer Modules

When the runtime fails during startup, isolate the module that causes it. In Designer, open Runtime → Startup, clear the modules you suspect under Startup Modules on the profile you start, and start the runtime. Turn the modules back on one at a time to find the one that fails. See Runtime Startup Reference.

Preventive Maintenance

Daily Checks

• Review error logs
• Check device status
• Monitor performance
• Verify backups

Weekly Tasks

• Archive logs
• Review alarm statistics
• Check disk space
• Test redundancy

Monthly Maintenance

• Update software
• Optimize databases
• Review security logs
• Performance analysis

Getting Help

Before Contacting Support

1. Document the issue (exact errors, steps to reproduce)
2. Gather diagnostics (logs, system specs)
3. Try standard remedies

Support Resources

• Documentation: docs.frameworkx.com
• Knowledge Base: Search error codes
• Community Forum: Share with other users
• Technical Support: Include diagnostic package

In this section...