🔧 Troubleshooting

🐛 Common Errors & Solutions

Troubleshooting guide for common reaction issues and debugging strategies.

🚀 Use Gradual Deployment

1. 🧪 Test Environment

Deploy with enabled: false first.

2. 🎯 Limited Scope

Start with specific file patterns or processes.

3. 👁️ Monitoring

Watch logs carefully for unexpected behavior.

4. 📈 Gradual Expansion

Slowly expand scope and enable more reactions.

5. 🚀 Production

Only deploy fully tested reactions to production.

🐛 Debugging and Troubleshooting

📝 Logging for Debugging

Use comprehensive logging to debug reaction issues:

reactions:
  - format: js
    code: |
      function process(data) {
        Info("=== REACTION DEBUG START ===");
        Info("Kind: " + kind);
        Info("Name: " + name);
        Info("UUID: " + uuid);

        // Log data structure
        Info("Data keys: " + Object.keys(data).join(", "));

        if (data.process) {
          Info("Process PID: " + data.process.pid);
          Info("Process CMD: " + data.process.cmd);
        }

        // Test helper functions
        let testResult = DataSet("debug_test", "success");
        Info("DataSet test result: " + testResult);

        let retrieved = DataGet("debug_test");
        Info("DataGet test result: " + retrieved);

        Info("=== REACTION DEBUG END ===");
      }

⚠️ Error Handling

Implement proper error handling:

reactions:
  - format: js
    code: |

      function process(data) {
        try {
          // Main reaction logic
          let result = NetBlockIp();
          if (result !== 0) {
            Error("Failed to block IP: " + Errno());
          }

          // File operations with error checking
          let writeResult = WriteFile("/tmp/reaction.log", "test");
          if (writeResult !== 0) {
            Error("Failed to write file: " + Errno());
          }

        } catch (error) {
          Error("Reaction error: " + error.toString());
        }
      }

Testing Reactions

Test Configuration

Create test reactions with disabled state:

- kind: test_reaction
  name: my_test_reaction
  enabled: false  # Start disabled for testing
  version: 1.0
  description: Test reaction for development
  breed: file_access
  mechanism: file_access
  importance: low

  bases:
    - dir: /tmp/test
      base: trigger.txt
  file_actions:
    - unlink

  reactions:
    - format: js
      code: |
        # JavaScript function here

        function process(data) {
          Info("=== TEST REACTION ===");
          Info("All systems operational");

          // Test all helper functions safely
          DataSet("test", "success");
          let value = DataGet("test");
          Info("Data store test: " + (value === "success" ? "PASS" : "FAIL"));

          DataDelete("test");
          Info("=== TEST COMPLETE ===");
        }

Configuration Validation

Jibril validates reaction configurations at startup. Common validation errors include:

Missing Required Fields

reactions:
  - format: js
    # ERROR: Missing 'code' field

Fix:

reactions:
  - format: js
    code: |
      function process(data) {
        Info("Valid reaction");
      }

Invalid Format

reactions:
  - format: python  # ERROR: Invalid format
    code: |
      print("Not supported")

Fix:

reactions:
  - format: js  # Valid: js or shell only
    code: |
      function process(data) {
        Info("Valid format");
      }

Missing Process Function (JavaScript)

reactions:
  - format: js
    code: |
      # ERROR: Missing process() function
      Info("This won't work");

Fix:

reactions:
  - format: js
    code: |
      function process(data) {
        Info("This will work");
      }

Network Helper Without netpolicy Plugin

reactions:
  - format: js
    code: |
      function process(data) {
        NetBlockIp(); # ERROR: Requires netpolicy feature enabled
      }