Troubleshooting Guide

​

Policy Not Enforcing

1. Verify mode is 'ENFORCE' (not 'MONITOR' or 'REPORT_ONLY')
2. Check if PLAN_ONLY mode is enabled (plan_only_mode: true skips enforcement)
3. Verify the rule condition matches your request’s action string exactly
4. Check engine.getStatus() to confirm rules are loaded

console.log(engine.getStatus());
// { mode: 'ENFORCE', modules: [...], freeze_rules: 3, policy_version: '2.1.0' }

​

FREEZE Rule Not Blocking

1. FREEZE rules match on the action field — verify exact string match
2. FREEZE rules are evaluated in pre-evaluation — they run before modules
3. Check if the request is using evaluateV12() (v1.2 method bypasses pre-evaluation)

// ✅ v1.3 evaluate() — FREEZE rules active
const decision = await engine.evaluate(request, ctx);

// ❌ evaluateV12() — FREEZE rules NOT checked
const decision = await engine.evaluateV12(request, ctx);

​

Bundle Signature Verification Failing

1. Verify the public key matches the private key used to sign the bundle
2. Check that the bundle file hasn’t been modified after signing
3. Verify the GOVERNANCE_PUBLIC_KEY environment variable is set correctly

// Debug: check what key is being used
console.log('Key length:', process.env.GOVERNANCE_PUBLIC_KEY?.length);

// Re-sign the bundle if it was modified
// tealtiger-cli bundle sign --input ./bundle/ --key governance-key.pem --output bundle.signed.json

​

NHI Verification Failing

1. Verify agentId is passed in the evaluation context
2. Verify the agent is registered in the NHI inventory with status active
3. Check that the action is within the agent’s registered scopes
4. If attestation is required, verify the token is valid and not expired

const decision = await engine.evaluate(request, {
  correlation_id: uuid(),
  agentId: 'support-bot-001',  // Must match NHI registry
  attestation: { token: jwtToken, method: 'signed-jwt' },  // If required
});

​

Approval Token Expired

1. Approval tokens have a TTL (default: 10 minutes)
2. The token may have expired before the approver responded
3. Re-evaluate the request to get a fresh token

try {
  await engine.approveDecision(token, { approvedBy: '[email protected]', justification: '...' });
} catch (e) {
  if (e instanceof ApprovalExpiredError) {
    // Re-evaluate to get a new token
    const newDecision = await engine.evaluate(request, ctx);
  }
}

​

Hot-Swap Rejected

1. Bundle schema validation failed — check the bundle structure
2. Bundle integrity hash doesn’t match signature
3. Bundle requires capabilities the engine doesn’t support (capability negotiation)
4. Previous bundle is retained on failure — governance continues uninterrupted

try {
  await engine.loadPolicy(newBundle);
} catch (e) {
  console.error('Swap failed:', e.message);
  // Previous bundle still active — no governance gap
}

​

TealClassifier Model Not Loading

1. Verify the ONNX model file exists at the configured path
2. Check that onnxruntime-node is installed (npm install onnxruntime-node)
3. Verify the model is compatible with the installed ONNX Runtime version
4. Fallback to regex_only is automatic — governance continues without ML

// Check classifier status
const status = engine.getStatus();
console.log(status.modules.classifier);
// { mode: 'regex_only', fallback_active: true, reason: 'ONNX_LOAD_FAILED' }

​

Cost Anomaly False Positives

1. The baseline may not have enough samples yet (min_samples not reached)
2. Reduce sensitivity: anomaly: { sensitivity: 'low' }
3. Increase the spike multiplier: spike_multiplier: 20
4. Reset the baseline after a legitimate usage pattern change

// Check anomaly status
const anomaly = await monitor.get_anomaly_status('agent-001');
console.log(anomaly.baseline.sample_count);  // Need min_samples before alerting

​

Drift Detection False Positives

1. Verify min_samples has been reached (default: 100)
2. If agent behavior legitimately changed, reset the baseline
3. Reduce sensitivity: drift: { sensitivity: 'low' }

// Reset baseline after legitimate behavior change
await drift.reset_baseline('agent-001');

​

Session TTL Expired

1. Default session TTL is 8 hours — check if the session has been running longer
2. Increase TTL if needed: temporal: { session_ttl: '24h' }
3. Implement session renewal in your application

​

Performance Issues

1. How many modules are registered? Each adds 1-3ms
2. Is TealClassifier using ensemble_union? Switch to regex_only for speed
3. Are post-hooks blocking? They should be async
4. Is the drift baseline window too large?

# Run benchmark to identify bottleneck
npx tealtiger benchmark --modules classifier,drift,monitor --iterations 1000

​

Getting Help