Error Codes¶

ACGP error codes and troubleshooting.

Error Code Format¶

ACGP-XXXX: Error description

Common Errors¶

ERR-1001: Invalid Trace Format¶

Cause: Cognitive trace is malformed or missing required fields

Solution: - Check trace has reasoning, action, and parameters - Validate JSON structure - See Cognitive Traces

ERR-1002: Authentication Failed¶

Cause: Invalid API key or certificate

Solution: - Verify API key is correct - Check certificate expiration - Confirm endpoint URL

ERR-1003: Governance Tier Invalid¶

Cause: Governance Tier value not recognized

Solution: - Use a valid serialized Governance Tier value: GT-0 through GT-5 - Check for typos

ACGP-2001: Evaluation Timeout¶

Cause: Evaluation took too long

Solution: - Simplify trace - Check network latency - Consider a lower Governance Tier when latency pressure matters more than deeper default scrutiny

ACGP-3001: Tripwire Exceeded¶

Cause: Action exceeded defined limit

Solution: - Review tripwire configuration - Check if limit is appropriate - Adjust parameters

ACGP-3002: Rate Limit Exceeded¶

Cause: Too many evaluation requests in time window

Solution: - Implement request queuing - Increase rate limit in configuration - Use batch evaluation for multiple traces

ACGP-3003: Trust Debt Threshold Exceeded¶

Cause: Agent trust debt exceeded a configured runtime threshold or triggered trust-policy review

Solution: - Review recent interventions and any orthogonal flags contributing to trust debt - Check trust debt thresholds, decay, and trust-provider policy configuration - Use governed recovery or supervisory review rather than ad hoc trust resets

ACGP-4001: Blueprint Not Found¶

Cause: Specified blueprint does not exist

Solution: - Check blueprint name spelling - Verify blueprint is registered - Use default blueprint if unsure

ACGP-4002: Blueprint Validation Failed¶

Cause: Blueprint YAML is malformed or invalid

Solution: - Validate YAML syntax - Check required fields are present - See Blueprint Schema

ACGP-4003: Blueprint Version Mismatch¶

Cause: Blueprint version incompatible with SDK

Solution: - Update SDK to latest version - Downgrade blueprint to compatible version - Check current compatibility in ACGP-6 conformance

INVALID_BLUEPRINT_WEIGHTS¶

Cause: Declared CTQ metric weights do not sum to 1.0 within ±0.001 tolerance

Solution: - Ensure all declared CTQ weights sum to 1.0 - Correct out-of-range or malformed numeric values - Re-validate blueprint before load; implementations MUST NOT auto-normalize

ACGP-5001: Cryptographic Verification Failed¶

Cause: Signature or hash verification failed (Safety-Critical profile)

Solution: - Check key configuration - Verify certificate chain - Ensure HSM is accessible

ACGP-5002: Consensus Not Reached¶

Cause: Distributed stewards failed to reach agreement (Safety-Critical profile)

Solution: - Check network connectivity between nodes - Verify quorum configuration - Review timeout settings

ACGP-5003: Audit Log Tampered¶

Cause: Audit log integrity check failed

Solution: - Investigate potential security breach - Restore from verified backup - Contact security team

ACGP-6001: Context Window Exceeded¶

Cause: Cognitive trace too large for evaluation

Solution: - Reduce reasoning length - Summarize context - Split into multiple traces

ACGP-6002: Unsupported Action Type¶

Cause: Action type not recognized by blueprint

Solution: - Check action name in blueprint - Register custom action type - Use generic action category

ACGP-6003: Invalid Parameter Format¶

Cause: Action parameters don't match expected schema

Solution: - Check parameter types - Validate against blueprint schema - See action documentation

ACGP-7001: Steward Unavailable¶

Cause: Governance steward service is down

Solution: - Check service health - Implement fallback policy - Use local caching if available

ACGP-7002: Network Timeout¶

Cause: Request to steward timed out

Solution: - Check network connectivity - Increase timeout configuration - Consider a lower Governance Tier for faster response

ACGP-7003: Service Overloaded¶

Cause: Steward service at capacity

Solution: - Implement exponential backoff - Queue non-critical evaluations - Scale steward instances

Error Categories¶

Code Range	Category	Description
ACGP-1xxx	Validation	Input validation errors
ACGP-2xxx	Evaluation	Evaluation process errors
ACGP-3xxx	Policy	Policy and limit violations
ACGP-4xxx	Blueprint	Blueprint-related errors
ACGP-5xxx	Security	Security and cryptographic errors
ACGP-6xxx	Format	Data format and size errors
ACGP-7xxx	Infrastructure	Service and network errors

Handling Errors in Code¶

from acgp import CognitiveTrace, GovernanceSteward, PostgresStateStorage, ACGPError, TripwireError, ValidationError

steward = GovernanceSteward.production(
    blueprint_file="blueprint.yaml",
    state_storage=PostgresStateStorage(connection_string="postgresql://runtime/acgp"),
)
trace = CognitiveTrace(action="refund", governance_tier="GT-2")

try:
    result = steward.evaluate(trace)
except ValidationError as e:
    # Handle input validation issues
    log.error(f"Invalid trace: {e.code} - {e.message}")
except TripwireError as e:
    # Handle policy violations
    log.warning(f"Tripwire triggered: {e.tripwire_name}")
    escalate_to_human(trace)
except ACGPError as e:
    # Handle all other ACGP errors
    log.error(f"ACGP error: {e.code} - {e.message}")
    apply_fallback_policy(trace)

Glossary Troubleshooting