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 "FrameworX Runtime"

# 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 FrameworX* | 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:"Solution.tproj" 
  /SaveLog:3 
  /AutoRunDiagnostics:30 
  /LogDeviceWriteStartup

External Tools

powershell

# Check service status
Get-Service -Name "FrameworX*"

# Monitor process
Get-Process FrameworX* | Select CPU, WS, Handles

# Check network connections
Get-NetTCPConnection -LocalPort 3101

# Review event logs
Get-EventLog -LogName Application -Source FrameworX -Newest 50

Recovery Procedures

Database Recovery

Backup Restoration:

sql

RESTORE DATABASE FrameworX 
FROM DISK = 'C:\Backup\FrameworX.bak'
WITH REPLACE

Database Repair:

sql

-- Check integrity
DBCC CHECKDB('FrameworX')

-- Repair minor issues
DBCC CHECKDB('FrameworX', REPAIR_REBUILD)

Solution Recovery

1. Try opening in Designer read-only mode
2. Export configuration to XML
3. Create new solution
4. Import XML configuration
5. Test thoroughly

Emergency Recovery Mode

cmd

# Start in safe mode
FrameworX.exe /safe

# Reset to defaults
FrameworX.exe /reset

# Skip module loading
FrameworX.exe /nomodules

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...