Troubleshooting Guide

Troubleshooting Guide

Overview

This guide provides troubleshooting methods for common issues with RAILWISE products (CLI, WorkWise, TSM, OS). Follow the diagnostic steps to quickly locate and resolve problems.

CLI Troubleshooting

Issue 1: Installation Failure

Symptom: npm install fails with permission or network errors

Diagnosis:

# Check Node.js version
node --version  # Should be v18+

# Check npm version
npm --version   # Should be v10+

# Check network
ping registry.npmjs.org

Solutions:

Cause	Solution
Permission error	Use sudo (macOS/Linux) or run as Administrator (Windows)
Network timeout	Use mirror: npm install -g @railwise/cli --registry=https://registry.npmmirror.com
Node.js version too low	Upgrade Node.js to v18+

Issue 2: Command Not Found

Symptom: railwise: command not found

Diagnosis:

# Check npm global directory
npm config get prefix

# Check PATH
echo $PATH  # macOS/Linux
# or
$env:PATH   # PowerShell

Solution:

# Add npm global directory to PATH
export PATH="$PATH:$(npm config get prefix)/bin"

Issue 3: Data Query Returns Empty

Symptom: railwise data list returns no results

Diagnosis:

# Check workspace initialization
ls ~/railwise-workspace/

# Check data directory
ls ~/railwise-workspace/data/

# Check project configuration
railwise config get project

Solution:

# Import sample data
railwise data import --sample

# Or connect to remote data source
railwise config set api.url https://api.railwise.example.com

WorkWise Troubleshooting

Issue 1: Installation Failure

Symptom: Installation fails or application cannot start

Diagnosis:

• Check system requirements
• Check disk space
• Check GPU compatibility

Solutions:

Cause	Solution
Missing dependencies	Install Visual C++ Redistributable (Windows)
GPU compatibility	Start with --disable-gpu flag
Disk space insufficient	Free up disk space or change installation path

Issue 2: Blank Interface After Startup

Symptom: Interface is blank or unresponsive after startup

Solution:

# Disable GPU acceleration
WorkWise --disable-gpu

# Or reset configuration
WorkWise --reset-config

Issue 3: Cannot Connect to TSM Server

Symptom: Cannot connect to TSM server or data sync fails

Diagnosis:

1. Check network connection
2. Confirm server address and port are correct
3. Check firewall settings

Solution:

# Test connection
curl http://tsm-server:8080/api/v1/health

# Check firewall
sudo ufw status
sudo ufw allow 8080

TSM Troubleshooting

Issue 1: Service Startup Failure

Symptom: Docker containers fail to start

Diagnosis:

# Check port occupancy
sudo lsof -i :8080

# Check logs
docker-compose logs tsm-server

Solutions:

Cause	Solution
Port conflict	Change port mapping in docker-compose.yml
Configuration error	Check .env file configuration
Database connection failure	Check database container status

Issue 2: Database Connection Failure

Symptom: Application cannot connect to database

Diagnosis:

# Check database container status
docker-compose ps postgres

# Test database connection
docker-compose exec tsm-server npx pg-ping --host postgres --port 5432

Solution:

# Restart database container
docker-compose restart postgres

# Check database logs
docker-compose logs postgres

Issue 3: Instrument Communication Failure

Symptom: Total station cannot connect or data acquisition fails

Diagnosis:

1. Check instrument power status
2. Check network connection
3. Check instrument remote mode

Solution:

# Test network connection
ping 192.168.1.100

# Check instrument status in TSM interface
# System Management > Instrument Management > Test Connection

OS Troubleshooting

Issue 1: Cannot Login

Symptom: Login fails or account not activated

Solutions:

Cause	Solution
Wrong username/password	Reset password or contact administrator
Account not activated	Contact administrator to activate
Account locked	Wait for auto-unlock or contact administrator

Issue 2: Missing Features

Symptom: Some features are not visible or inaccessible

Diagnosis:

• Check current role permissions
• Confirm correct project is selected
• Check if feature is enabled

Solution:

1. Confirm current role permissions in Personal Center > Permissions
2. Contact administrator to apply for permissions
3. Confirm correct project is selected

Issue 3: Report Generation Failure

Symptom: Report generation fails or times out

Diagnosis:

• Check if selected monitoring points have data
• Check if time range is reasonable
• Check if template configuration is correct

Solution:

1. Confirm selected monitoring points have data
2. Narrow time range
3. Try other templates
4. Contact technical support if problem persists

Escalation Path

If the above solutions cannot resolve the issue, please escalate through the following channels:

Level	Channel	Response Time	Applicable Scenario
Level 1	Documentation / FAQ	Immediate	Common issues
Level 2	Community Forum	24 hours	General questions
Level 3	Technical Support Email	48 hours	Complex issues
Level 4	Phone Support	4 hours	Urgent issues
Level 5	On-site Support	Negotiated	Critical issues

Contact Information:

• Technical Support Email: support@railwise.cn
• Phone Support: 400-XXX-XXXX (Working hours 9:00-18:00)
• Community Forum: GitHub Discussions

Diagnostic Tools

CLI Diagnostic

# Comprehensive diagnosis
railwise doctor

# Verbose diagnosis
railwise doctor --verbose

# Check specific module
railwise doctor --module data

TSM Diagnostic

# Service health check
curl http://tsm-server:8080/api/v1/health

# Database connection check
docker-compose exec tsm-server npm run db:check

# Instrument communication check
docker-compose exec tsm-server npm run instrument:check

Related Documents

• CLI Troubleshooting
• TSM Troubleshooting
• Developer Troubleshooting

---

RailWise · Smart Monitoring — Engineering Surveying and Safety Monitoring Digital Solutions