Troubleshooting

Troubleshooting

Common Issues

”Policy validation failed”

Your policy file has syntax errors.

Solution:

• Check YAML syntax (indentation, colons)
• Validate against the schema
• Check file path is correct

”CEL expression error”

Invalid CEL syntax in a rule.

Solution:

• Check CEL syntax
• Ensure referenced fields exist
• Test expression in isolation

”Webhook signature invalid”

Webhook signature verification failed.

Solutions:

• Ensure rawBodyCapture() is before express.json()
• Verify secret matches provider dashboard
• Check for proxy stripping headers

High Latency

Solutions:

• Use embedded deployment (fastest)
• Enable Unix socket for sidecar
• Enable client-side caching

Debug Logging

app.use(contractshield({
  policy: './policy.yaml',
  logger: (decision, req) => {
    console.log('Path:', req.path);
    console.log('Decision:', decision.action);
    console.log('Rule hits:', decision.ruleHits);
  }
}));

Getting Help

1. Check this documentation
2. Search GitHub Issues
3. Ask in GitHub Discussions
4. Pro customers: [email protected]