Troubleshooting

Separate invalid input, policy failure and environment issues.

AgentReady exit codes distinguish a valid policy failure from CLI usage errors and unexpected internal failures. This page keeps troubleshooting inside the current Community behavior.

Exit 0Scan and policy passed
Exit 1Valid scan, policy failed
Exit 2 or 3Usage error or internal error

Invalid input

Exit code 2 usually means missing command arguments, unsupported scan type, missing file, invalid policy value or an input the parser cannot read. Check openapi versus mcp and quote paths with spaces.

Policy failure

Exit code 1 is expected when the scan is valid but the configured gate fails. Reports and contracts should still exist when the scan completed.

Output paths

Use --out ./agentready-output or an explicit directory. OpenAPI writes agentready-report.md and agentready.json; MCP writes agentready-mcp-report.md and agentready-mcp.json.

GitHub Action failures

Verify Node.js 20 setup, permissions: contents: read, the input file path and the Action inputs. A policy failure is not a broken Action.

Paths containing spaces

Quote local paths in shell commands and workflow inputs. The current smoke tests cover paths containing spaces without changing CLI behavior.

npx @timeproofs/agentready@alpha scan openapi "contracts/My API/openapi.json" --out "agentready output" --min-score 75 --fail-on critical

TimeProofs AgentReady does not guarantee that an AI agent will never fail. It identifies structural risks that may cause AI agents to misuse APIs, tools or MCP servers.

Troubleshooting can identify scanner, input and policy issues. It does not provide runtime monitoring, legal advice, certification or guaranteed remediation.

AgentReady at a glance

Troubleshooting separates invalid input, policy failure, output path issues, path spaces and GitHub Action environment failures. AgentReady is a product and candidate open standard for static pre-deployment analysis. It is not a runtime firewall, independent certification, official standards-body standard or guaranteed-safety system.

Availability
AgentReady Community is free and available. AgentReady Pro is planned and not purchasable.
Language
English is the current canonical language. No translated alternate route is published for this page.
Sources

AGENTREADY_MASTER_PLAN.mdGLOBAL_STANDARD_SITE_PROGRAM.mdSEO_GEO_AI_FIRST_REQUIREMENTS.mdSITE_COPY_GUIDE.mdCLI_PUBLIC_DISTRIBUTION.md