RAILWISE-CLI Troubleshooting Guide

RAILWISE-CLI Troubleshooting Guide

Target Audience: CLI daily users, on-site project technicians, operations support personnel
Estimated Reading Time: 15 minutes
Prerequisites: RAILWISE-CLI installed and previously executed

---

1. Installation & Startup Issues

1.1 Installation Failure: Permission Denied

Symptom:

bun install -g @railwise/cli
# EACCES: permission denied, mkdir '/usr/local/lib/node_modules/@railwise'

Cause: Global installation directory requires administrator privileges.

Solutions:

# Option 1: User-level installation (recommended)
bun install -g @railwise/cli --prefix ~/.local
export PATH="$HOME/.local/bin:$PATH"

# Option 2: Use sudo (macOS/Linux)
sudo bun install -g @railwise/cli

# Option 3: Windows — run PowerShell as administrator
# Right-click PowerShell → Run as administrator

1.2 Installation Failure: Network Timeout

Symptom:

error: package "@railwise/cli" not found
# Or registry connection timeout

Solutions:

# Configure China mirror registry
bun config set registry https://registry.npmmirror.com

# Or use company private registry
bun config set registry https://npm.railwise.cn

# Verify configuration
bun config get registry

1.3 Startup Error: Bun Version Incompatible

Symptom:

railwise --version
# error: Unsupported Bun version. Required: >=1.1.0, Found: 1.0.35

Solutions:

# Upgrade Bun
bun upgrade

# Or reinstall
curl -fsSL https://bun.sh/install | bash

---

2. Configuration Issues

2.1 Initialization Failure: Directory Already Exists

Symptom:

railwise init --project "Test Project"
# Error: .railwise directory already exists

Solutions:

# Option 1: Force re-initialization (after backup)
mv .railwise .railwise.backup.$(date +%Y%m%d)
railwise init --project "Test Project"

# Option 2: Non-interactive mode, skip existing files
railwise init --project "Test Project" --force --skip-existing

2.2 Configuration File Parse Error

Symptom:

railwise run workflow.yaml
# Error: YAML parse error at .railwise/config.yaml: line 23, column 5

Troubleshooting Steps:

1. Check indentation: YAML uses space indentation, Tab is prohibited
2. Check special characters: Add space after colon for Chinese characters key: value
3. Validate syntax:

   railwise config validate
   # Or use online tool https://www.yamllint.com/

4. Common error examples:

   # ❌ Error: Tab indentation
   project:
     name: "Project"    # ← Tab used here
   
   # ✅ Correct: Two-space indentation
   project:
     name: "Project"

2.3 Coordinate System Configuration Invalid

Symptom: Import prompts “Unknown coordinate system: XXX”

Checklist:

Check Item	Command/Operation
Coordinate system name spelling	railwise config get coordinate_systems.available
EPSG code validity	Visit https://epsg.io/ to verify
Projection parameter completeness	Check central_meridian, false_easting and other required fields
Configuration file path	Confirm modification is to current project’s .railwise/config.yaml

---

3. Data Import Issues

3.1 Import File No Response

Symptom:

railwise surveyor import data/large_file.gsi
# Long time no output, high CPU usage

Troubleshooting Steps:

1. Check file size: Large files (>100MB) recommend batch import
2. Enable verbose logging:

   railwise surveyor import data/large_file.gsi --verbose

3. Check file encoding:

   file -i data/large_file.gsi
   # Output should be: text/plain; charset=utf-8

4. Try limiting import scope:

   railwise surveyor import data/large_file.gsi --max-records 1000

3.2 Data Parse Error: Format Mismatch

Symptom:

# Error: Failed to parse record at line 156: Unknown field code "99"

Solutions:

# Option 1: Skip unknown fields
railwise surveyor import data.gsi --skip-unknown-fields

# Option 2: Use generic CSV format as intermediate
# 1. First export to CSV using instrument native software
# 2. Write column mapping file (see cli-data-formats.md)
railwise surveyor import data.csv --format csv --mapping map.yaml

# Option 3: Contact technical support for dedicated parser

3.3 Chinese Character Garbled

Symptom: After import, point IDs and remarks display as ???? or garbled blocks.

Troubleshooting & Solutions:

# Step 1: Detect original file encoding
file -i data.gsi
# Output example: text/plain; charset=iso-8859-1

# Step 2: Convert encoding
iconv -f GBK -t UTF-8 data.gsi > data_utf8.gsi
# Or
iconv -f ISO-8859-1 -t UTF-8 data.gsi > data_utf8.gsi

# Step 3: Re-import
railwise surveyor import data_utf8.gsi --encoding utf-8

提示

for f in data/*.gsi; do
  iconv -f GBK -t UTF-8 "$f" > "${f%.gsi}_utf8.gsi"
done

---

4. Workflow Execution Issues

4.1 Workflow Execution Failure: Step Timeout

Symptom:

# Error: Step "Adjustment Calculation" timed out after 300s

Solutions:

# Add timeout setting in workflow
steps:
  - name: "Adjustment Calculation"
    agent: "adjuster"
    action: "adjust"
    timeout: 600                        # Increase to 10 minutes
    # Or set to 0 for unlimited
    # timeout: 0

4.2 Workflow Execution Failure: Out of Memory

Symptom:

# Error: JavaScript heap out of memory
# Or system memory insufficient

Solutions:

# Option 1: Increase Node/Bun memory limit
export BUN_JSC_memoryLimit=4096       # 4GB
railwise run workflow.yaml

# Option 2: Reduce concurrency
# In .railwise/config.yaml
performance:
  max_concurrent_agents: 1

# Option 3: Batch process large data
steps:
  - name: "Batch Import"
    agent: "surveyor"
    action: "import"
    input: "data/"
    params:
      batch_size: 500                   # Process 500 records per batch

4.3 Condition Judgment Not Working

Symptom: Set condition but step always executes or always skips.

Checklist:

Check Item	Description
Variable name spelling	Confirm exact match with output_var
Data type	Numeric vs string comparison in condition expressions must be consistent
Boolean format	Use true/false not "true"/"false"
Expression syntax	Use == not =

Correct Example:

steps:
  - name: "Check"
    agent: "inspector"
    action: "check"
    output_var: "check_result"         # Outputs boolean

  - name: "Conditional Execution"
    agent: "adjuster"
    action: "adjust"
    condition: "{{check_result}} == true"   # Correct
    # ❌ Error: condition: "check_result == true" (missing variable syntax)

---

5. Error Code Quick Reference

Error Code	Meaning	Common Cause	Solution
RWI-001	Config file not found	railwise init not executed	Run initialization command
RWI-002	Config file parse failed	YAML syntax error	Check indentation, special characters
RWI-003	Unknown agent	Agent name spelling error	Run railwise agent list to view
RWI-004	Unknown action	Agent does not support this action	Consult agent documentation
RWI-005	Data format not supported	Format identifier error or file corrupted	Check file header or use --format
RWI-006	Coordinate system undefined	Coordinate system name spelling error	Check config.yaml coordinate system config
RWI-007	File encoding error	Encoding declaration mismatch	Use file -i to detect and convert
RWI-008	Tolerance exceeded	Observation data precision insufficient	Check instrument settings, observation conditions
RWI-009	Gross error detection failed	Poor data quality or insufficient redundancy	Increase observation times or check instrument
RWI-010	Network request failed	External API unreachable	Check network, proxy configuration
RWI-011	Workflow circular dependency	Circular references between steps	Check input_var reference chain
RWI-012	Parallel step conflict	Parallel steps output variable name collision	Ensure output_var uniqueness
RWI-013	Plugin load failed	Plugin path error or version incompatible	Check plugin configuration and CLI version
RWI-014	Out of memory	Data volume too large or concurrency too high	Reduce batch size, lower concurrency
RWI-015	Insufficient disk space	Output directory space insufficient	Clean disk or change output path

---

6. Performance Optimization Recommendations

6.1 Big Data Processing Optimization

Scenario	Optimization Strategy	Expected Effect
Single import >100k records	Batch import, batch_size: 5000	Reduce memory peak 60%
Multi-period data merge analysis	Use database backend (SQLite/PostgreSQL)	Query speed 10x improvement
Repeatedly execute same workflow	Enable cache cache.enabled: true	80% speedup on second execution
Network storage (NAS/SMB) data	Copy to local SSD first then process	I/O latency reduced 90%

6.2 Workflow Acceleration Configuration

.railwise/config.yaml

performance:
  max_concurrent_agents: 4            # Adjust based on CPU core count
  enable_parallel_processing: true

cache:
  enabled: true
  ttl: 86400

logging:
  level: "warn"                       # Reduce log output in production
  async: true                         # Async log writing

---

7. Getting Help

7.1 Built-in Help Commands

# View global help
railwise --help

# View subcommand help
railwise surveyor --help
railwise surveyor import --help

# View agent list
railwise agent list

# View workflow syntax
railwise workflow --help

7.2 Logs & Diagnostics

# Enable debug logging
railwise run workflow.yaml --verbose --log-level debug

# Export diagnostic bundle (for technical support analysis)
railwise diagnose --output diagnostic-bundle.zip

# View recent execution logs
railwise logs --last 10

7.3 Contact Technical Support

If the above solutions cannot resolve the issue, please prepare the following information before contacting technical support:

1. Environment info: OS, Bun version, CLI version (railwise --version)
2. Error logs: Full output after executing command with --verbose
3. Diagnostic bundle: Compressed package generated by railwise diagnose
4. Data sample: Minimum data file that can reproduce the issue (de-sensitized)

Contact:

• Technical support email: support@railwise.cn
• WeChat Work: RailWise Technical Support Group
• Phone: 0574-XXXX-XXXX (Weekdays 9:00-18:00)

---

8. Related Documents

• CLI Quick Start Guide — Quick start guide
• CLI Agent Configuration — Agent configuration details
• CLI Workflow Orchestration — Workflow orchestration
• CLI Data Formats — Data formats and import

---

Metadata Tags

---

Last updated: 2025-01-15 | Version v1.2.0 | © Ningbo RailWise Engineering Technology Co., Ltd.