# PACT Rule CLI - Troubleshooting Guide This comprehensive troubleshooting guide helps resolve common issues with PACT Rule CLI, covering installation problems, rule validation errors, compilation failures, and deployment issues. ## Table of Contents - [Installation Issues](#installation-issues) - [Rule Creation Problems](#rule-creation-problems) - [Validation Errors](#validation-errors) - [Compilation Failures](#compilation-failures) - [Testing Issues](#testing-issues) - [Deployment Problems](#deployment-problems) - [AI Features Issues](#ai-features-issues) - [Performance Issues](#performance-issues) - [Configuration Problems](#configuration-problems) - [Environment Setup](#environment-setup) - [Debug Mode](#debug-mode) - [Common Error Codes](#common-error-codes) - [Support Resources](#support-resources) ## Installation Issues ### Node.js Version Compatibility **Problem**: PACT Rule CLI fails to install or run with older Node.js versions. **Solution**: ```bash # Check current Node.js version node --version # Should be 18.0.0 or higher # Install latest Node.js from https://nodejs.org/ # Or use nvm for version management nvm install 18 nvm use 18 ``` ### Global Installation Failures **Problem**: `npm install -g pact-rule` fails with permission errors. **Solution**: ```bash # Option 1: Use sudo (Linux/macOS) sudo npm install -g pact-rule # Option 2: Configure npm to use different directory mkdir ~/.npm-global npm config set prefix '~/.npm-global' echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.profile source ~/.profile npm install -g pact-rule # Option 3: Use npx (no global installation) npx pact-rule --help ``` ### Module Resolution Errors **Problem**: `Cannot find module` errors after installation. **Solution**: ```bash # Clear npm cache npm cache clean --force # Reinstall npm uninstall -g pact-rule npm install -g pact-rule # Verify installation which pact-rule pact-rule --version ``` ## Rule Creation Problems ### YAML Syntax Errors **Problem**: Rule file has invalid YAML syntax. **Diagnosis**: ```bash # Validate YAML syntax python -m yaml < rules/my-rule.yaml # Or use online YAML validator # yamllint.com ``` **Common YAML Issues**: ```yaml # Wrong - Missing quotes around operators conditions: - field: amount operator: > # Should be ">" value: 10000 # Correct conditions: - field: amount operator: ">" value: 10000 # Wrong - Incorrect indentation conditions: - field: amount operator: ">" value: 10000 # Wrong indentation # Correct conditions: - field: amount operator: ">" value: 10000 ``` ### JSON Syntax Errors **Problem**: Rule file has invalid JSON syntax. **Diagnosis**: ```bash # Validate JSON syntax python -m json.tool < rules/my-rule.json # Or use jq jq . rules/my-rule.json ``` **Common JSON Issues**: ```json // Wrong - Trailing comma { "conditions": [ { "field": "amount", "operator": ">", "value": 10000, // Remove this comma } ] } // Wrong - Single quotes { 'name': 'my-rule' // Use double quotes } // Correct { "name": "my-rule", "conditions": [ { "field": "amount", "operator": ">", "value": 10000 } ] } ``` ## Validation Errors ### Schema Validation Failures **Problem**: Rule fails schema validation. **Common Error Messages and Solutions**: ```bash # Error: missing required property 'name' ``` **Solution**: Add the missing property ```yaml name: my-rule-name # Add this version: 1.0.0 conditions: [...] ``` ```bash # Error: /version: must match pattern "^\d+\.\d+\.\d+$" ``` **Solution**: Use semantic versioning ```yaml version: 1.0.0 # Correct format # Not: v1.0 or 1.0 ``` ```bash # Error: /conditions: must be array ``` **Solution**: Ensure conditions is an array ```yaml # Wrong conditions: field: amount operator: ">" value: 10000 # Correct conditions: - field: amount operator: ">" value: 10000 ``` ### Logic Validation Errors **Problem**: Rule contains logical contradictions. **Example**: ```yaml conditions: - field: amount operator: ">" value: 10000 - field: amount operator: "<" value: 5000 ``` **Solution**: ```bash # Check for contradictions pact-rule validate rules/my-rule.yaml --verbose # Fix contradictory conditions # Use OR logic or separate rules ``` ### Field Reference Errors **Problem**: Rule references non-existent fields. **Solution**: ```yaml # Document expected data structure # transaction.amount expects: # { # "transaction": { # "amount": 10000 # } # } conditions: - field: transaction.amount # Correct nested field reference operator: ">" value: 10000 ``` ## Compilation Failures ### Compilation Errors **Problem**: Rule fails to compile. **Diagnosis**: ```bash # Run with debug mode pact-rule compile rules/my-rule.yaml --debug # Check for specific errors pact-rule compile rules/my-rule.yaml --verbose ``` **Common Compilation Issues**: 1. **Invalid operator**: ```yaml # Wrong operator: "===" # Not supported # Correct operator: "=" # Use supported operators ``` 2. **Type mismatches**: ```yaml # Wrong conditions: - field: amount operator: ">" value: "10000" # String instead of number # Correct conditions: - field: amount operator: ">" value: 10000 # Number type: number # Explicit type ``` ### Output File Issues **Problem**: Cannot write compiled output. **Solution**: ```bash # Check directory permissions ls -la rules/ # Create output directory if needed mkdir -p dist/ # Specify custom output pact-rule compile rules/my-rule.yaml --output dist/my-rule.json # Check disk space df -h ``` ## Testing Issues ### Test Data Format Errors **Problem**: Test data file has incorrect format. **Correct Format**: ```json { "entries": [ { "id": "test-001", "transaction": { "amount": 15000 }, "user": { "kyc_status": "pending" } } ] } ``` **Common Mistakes**: ```json // Wrong - Missing entries wrapper [ { "id": "test-001", "amount": 15000 } ] // Wrong - Missing id field { "entries": [ { "transaction": { "amount": 15000 } } ] } ``` ### Test Execution Failures **Problem**: Tests fail unexpectedly. **Debugging Steps**: ```bash # Run with verbose output pact-rule test --rule my-rule --data test.json --verbose # Test single entry echo '{"entries": [{"id": "test-1", "amount": 15000}]}' | \ pact-rule test --rule my-rule --data - # Generate test report pact-rule test --rule my-rule --data test.json --report > test-report.txt ``` ### Field Path Issues **Problem**: Test data structure doesn't match rule expectations. **Solution**: ```bash # Rule expects: transaction.amount # Test data should have: { "entries": [ { "id": "test-001", "transaction": { # Nested structure "amount": 15000 } } ] } # Not: { "entries": [ { "id": "test-001", "amount": 15000 # Wrong: not nested } ] } ``` ## Deployment Problems ### Network Connection Issues **Problem**: Cannot connect to deployment network. **Diagnosis**: ```bash # Check network status pact-rule status --network testnet # Test API endpoint curl https://testnet.pact.protocol/health # Check configuration cat .pactrc | jq '.networks' ``` **Solutions**: ```bash # Configure network endpoints cat > .pactrc << EOF { "networks": { "testnet": { "endpoint": "https://testnet.pact.protocol", "chainId": "5" }, "mainnet": { "endpoint": "https://mainnet.pact.protocol", "chainId": "1" } } } EOF # Use custom endpoint pact-rule deploy --rule my-rule --network testnet \ --endpoint https://custom-endpoint.com ``` ### Authentication Failures **Problem**: Deployment fails with authentication error. **Solutions**: ```bash # For blockchain deployment export PACT_PRIVATE_KEY="your-private-key" # For API deployment export PACT_API_KEY="your-api-key" # Test authentication pact-rule deploy --rule test-rule --dry-run --debug ``` ### Gas Estimation Issues **Problem**: Transaction runs out of gas. **Solutions**: ```bash # Estimate gas first pact-rule deploy --rule my-rule --dry-run # Deploy with higher gas limit pact-rule deploy --rule my-rule --gas-limit 500000 # Optimize rule before deployment pact-rule compile rules/my-rule.yaml --optimize pact-rule deploy --rule my-rule ``` ## AI Features Issues ### OpenAI API Issues **Problem**: AI features fail with API errors. **Diagnosis**: ```bash # Check API key echo $OPENAI_API_KEY # Test API connectivity curl -H "Authorization: Bearer $OPENAI_API_KEY" \ https://api.openai.com/v1/models ``` **Solutions**: ```bash # Set correct API key export OPENAI_API_KEY="sk-your-actual-api-key" # Use different model pact-rule nl2rule "Your prompt" --model gpt-3.5-turbo # Check API quota # Visit https://platform.openai.com/account/usage ``` ### NL2Rule Generation Failures **Problem**: Natural language rule generation fails. **Common Issues and Solutions**: 1. **Validation errors in generated rule**: ```bash # Use auto-fix flag pact-rule nl2rule "Block high value transactions" --fix # Generate in different format pact-rule nl2rule "Block high value transactions" --format json ``` 2. **Unclear prompts**: ```bash # Bad prompt pact-rule nl2rule "Block bad stuff" # Better prompt pact-rule nl2rule "Block transactions over $10000 from unverified users" # Best prompt - specific and clear pact-rule nl2rule "Block wire transfers exceeding $10000 when user KYC status is not verified" ``` 3. **Complex rule generation**: ```bash # Break into multiple rules pact-rule nl2rule "Block transactions over $10000 without KYC" pact-rule nl2rule "Flag rapid sequential transactions" pact-rule nl2rule "Require MFA for account changes" ``` ### Rule Expansion Failures **Problem**: Rule expansion command fails. **Solutions**: ```bash # Check file exists and is valid pact-rule validate rules/my-rule.yaml # Try with different model pact-rule expand rules/my-rule.yaml --model gpt-3.5-turbo # Simplify rule for analysis # Remove complex conditions temporarily ``` ## Performance Issues ### Slow Compilation **Problem**: Rule compilation takes too long. **Solutions**: ```bash # Skip optimization for development pact-rule compile rules/my-rule.yaml --no-optimize # Compile multiple rules in parallel for rule in rules/*.yaml; do pact-rule compile "$rule" & done wait # Use caching (if implemented) export PACT_CACHE_DIR=/tmp/pact-cache ``` ### Memory Issues **Problem**: Out of memory errors. **Solutions**: ```bash # Increase Node.js memory limit export NODE_OPTIONS="--max-old-space-size=4096" pact-rule compile rules/large-rule.yaml # Process rules in batches find rules -name "*.yaml" | xargs -n 10 -P 2 pact-rule compile ``` ### Large Rule Files **Problem**: Rule files are too large to process. **Solutions**: ```bash # Split large rule into multiple smaller rules # Instead of one rule with 100 conditions # Create 10 rules with 10 conditions each # Use rule composition # base-rule.yaml # extension-rule-1.yaml # extension-rule-2.yaml ``` ## Configuration Problems ### Configuration File Not Found **Problem**: PACT Rule cannot find configuration file. **Solutions**: ```bash # Create default configuration cat > .pactrc << 'EOF' { "logLevel": "info", "networks": { "testnet": { "endpoint": "https://testnet.pact.protocol", "chainId": "5" } } } EOF # Specify config path export PACT_CONFIG_PATH=/path/to/.pactrc pact-rule status # Use command line option pact-rule --config /path/to/config.json status ``` ### Invalid Configuration **Problem**: Configuration file has errors. **Diagnosis**: ```bash # Validate JSON syntax cat .pactrc | jq . # Check configuration pact-rule status --debug ``` **Common Configuration Issues**: ```json // Wrong - Comments not allowed in JSON { // This is a comment "logLevel": "info" } // Correct - No comments { "logLevel": "info" } // Wrong - Incorrect structure { "testnet": { "endpoint": "https://..." } } // Correct - Proper nesting { "networks": { "testnet": { "endpoint": "https://..." } } } ``` ## Environment Setup ### Development Environment **Problem**: Setting up development environment for rule creation. **Complete Setup**: ```bash # Create project structure mkdir pact-rules-project cd pact-rules-project # Initialize directories mkdir -p {rules,tests,schemas,dist} # Create configuration cat > .pactrc << 'EOF' { "logLevel": "debug", "networks": { "local": { "endpoint": "http://localhost:8545", "chainId": "1337" }, "testnet": { "endpoint": "https://testnet.pact.protocol", "chainId": "5" } } } EOF # Set environment variables cat > .env << 'EOF' PACT_CONFIG_PATH=./.pactrc PACT_LOG_LEVEL=debug OPENAI_API_KEY=your-key-here EOF # Create package.json for scripts cat > package.json << 'EOF' { "name": "pact-rules-project", "scripts": { "validate": "pact-rule validate --all", "compile": "for f in rules/*.yaml; do pact-rule compile \"$f\"; done", "test": "for f in rules/*.compiled.json; do name=$(basename \"$f\" .compiled.json); pact-rule test --rule \"$name\" --data \"tests/${name}-test.json\"; done", "deploy:test": "pact-rule deploy --network testnet --dry-run" } } EOF # Install PACT Rule CLI npm install -g pact-rule # Create example rule cat > rules/example-kyc.yaml << 'EOF' name: example-kyc version: 1.0.0 description: Example KYC rule conditions: - field: transaction.amount operator: ">" value: 10000 actions: - type: block params: reason: "KYC required" EOF # Create test data cat > tests/example-kyc-test.json << 'EOF' { "entries": [ { "id": "test-001", "transaction": { "amount": 15000 } } ] } EOF # Test setup pact-rule validate rules/example-kyc.yaml pact-rule compile rules/example-kyc.yaml pact-rule test --rule example-kyc --data tests/example-kyc-test.json ``` ### Production Environment **Problem**: Preparing rules for production deployment. **Setup**: ```bash # Production checklist #!/bin/bash echo "=== Production Deployment Checklist ===" # 1. Validate all rules echo "[ ] Validating rules..." if pact-rule validate --all --strict; then echo "[✓] All rules valid" else echo "[✗] Validation failed" exit 1 fi # 2. Run all tests echo "[ ] Running tests..." npm run test # 3. Check rule versions echo "[ ] Checking versions..." for rule in rules/*.yaml; do version=$(grep "version:" "$rule" | awk '{print $2}') echo " $(basename "$rule"): v$version" done # 4. Generate deployment report echo "[ ] Generating deployment report..." pact-rule list --network mainnet --json > deployment-report.json # 5. Backup current rules echo "[ ] Creating backup..." tar -czf "rules-backup-$(date +%Y%m%d-%H%M%S).tar.gz" rules/ echo "=== Ready for deployment ===" ``` ## Debug Mode ### Enabling Debug Output **Basic Debug Mode**: ```bash # Enable debug for specific command pact-rule compile rules/my-rule.yaml --debug # Enable debug globally export PACT_LOG_LEVEL=debug pact-rule validate --all # Maximum verbosity pact-rule --debug --verbose compile rules/my-rule.yaml ``` ### Debug Output Analysis **Understanding Debug Logs**: ```bash # Capture debug output pact-rule compile rules/my-rule.yaml --debug 2>&1 | tee debug.log # Filter for errors grep -i error debug.log # Filter for warnings grep -i warn debug.log # Look for specific components grep -i "validation" debug.log grep -i "compilation" debug.log ``` ### Advanced Debugging **Step-by-step Debugging**: ```bash # 1. Validate syntax echo "=== Validating Syntax ===" pact-rule validate rules/my-rule.yaml --verbose # 2. Check compilation echo "=== Compiling ===" pact-rule compile rules/my-rule.yaml --debug --no-optimize # 3. Test with minimal data echo "=== Testing ===" echo '{"entries": [{"id": "debug-1", "amount": 10001}]}' | \ pact-rule test --rule my-rule --data - --verbose # 4. Dry run deployment echo "=== Deployment Dry Run ===" pact-rule deploy --rule my-rule --dry-run --debug ``` ## Common Error Codes ### Error Code Reference | Code | Description | Solution | |------|-------------|----------| | `VALIDATION_ERROR` | Rule validation failed | Check rule syntax and schema | | `COMPILATION_ERROR` | Compilation failed | Review rule logic and operators | | `FILE_NOT_FOUND` | Input file missing | Verify file path | | `INVALID_SYNTAX` | YAML/JSON syntax error | Use validator to check syntax | | `SCHEMA_MISMATCH` | Schema validation failed | Match rule to schema requirements | | `TEST_FAILURE` | Test execution failed | Check test data format | | `DEPLOYMENT_ERROR` | Deployment failed | Verify network and credentials | | `AI_SERVICE_ERROR` | AI feature failed | Check API key and connectivity | ### Specific Error Solutions **ENOENT: no such file or directory**: ```bash # Check file exists ls -la rules/my-rule.yaml # Use absolute path pact-rule compile $(pwd)/rules/my-rule.yaml # Check current directory pwd ``` **EACCES: permission denied**: ```bash # Fix file permissions chmod 644 rules/my-rule.yaml # Fix directory permissions chmod 755 rules/ # Check ownership ls -la rules/ ``` **Unexpected token in JSON**: ```bash # Validate JSON cat rules/my-rule.json | jq . # Common fix - remove trailing commas sed -i 's/,\s*}/}/g' rules/my-rule.json sed -i 's/,\s*]/]/g' rules/my-rule.json ``` ## Support Resources ### Getting Help **Official Resources**: - **Documentation**: [docs.pact.protocol/rule](https://docs.pact.protocol/rule) - **GitHub Issues**: [github.com/pact-protocol/pact-rule/issues](https://github.com/pact-protocol/pact-rule/issues) - **API Reference**: [api-reference.md](api-reference.md) - **Architecture Guide**: [architecture.md](architecture.md) **Community Support**: - **Discord**: [discord.gg/pact-protocol](https://discord.gg/pact-protocol) - **Forum**: [forum.pact.protocol](https://forum.pact.protocol) - **Stack Overflow**: Tag questions with `pact-rule` **Emergency Support**: - **Security Issues**: [security@pact.protocol](mailto:security@pact.protocol) - **Critical Bugs**: [urgent@pact.protocol](mailto:urgent@pact.protocol) ### Reporting Issues **Bug Report Template**: ```markdown ## Bug Report **Environment**: - PACT Rule Version: [run `pact-rule --version`] - Node.js Version: [run `node --version`] - Operating System: [e.g., Ubuntu 20.04, macOS 12.0] - Configuration: [attach .pactrc if relevant] **Command**: ```bash pact-rule compile rules/my-rule.yaml ``` **Expected Behavior**: [What you expected to happen] **Actual Behavior**: [What actually happened] **Error Output**: ``` [Paste error messages here] ``` **Rule File**: ```yaml [Paste rule content if relevant] ``` **Steps to Reproduce**: 1. Create rule file with content above 2. Run command X 3. Observe error Y **Additional Context**: [Any other relevant information] ``` ### Contributing **Reporting Rule Issues**: ```bash # Create minimal reproduction mkdir bug-report cd bug-report # Create rule that demonstrates issue cat > problem-rule.yaml << 'EOF' # Your problematic rule here EOF # Create test case cat > test-case.json << 'EOF' # Your test data here EOF # Document steps cat > README.md << 'EOF' # Steps to reproduce: 1. Run: pact-rule compile problem-rule.yaml 2. Observe error: ... EOF # Create archive tar -czf bug-report.tar.gz . ``` --- **Need more help?** Check the [Quick Start Guide](quick-start.md) for basic usage or the [API Reference](api-reference.md) for detailed command documentation.