Text of github.github.com › gh-aw › troubleshooting › errors as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout.

Open the live page

Error Reference | GitHub Agentic Workflows

Skip to main content Error Reference This reference documents common error messages, organized by when they occur during the workflow lifecycle. Schema Validation Errors Section titled “Schema Validation Errors” Detected during compilation when frontmatter does not conform to the JSON schema. Error Cause Fix frontmatter not properly closed Missing closing --- delimiter Enclose frontmatter between two --- lines failed to parse frontmatter: ...

Invalid YAML syntax Check indentation (spaces, not tabs), colons followed by spaces, quoted special characters timeout-minutes must be an integer Wrong value type Use the documented type — e.g., timeout-minutes: 10 , not "10" Unknown property: ... Misspelled field name Apply the “Did you mean” suggestion; see Frontmatter Reference imports field must be an array of strings Wrong syntax for imports: Use list form: - shared/tools.md multiple agent files found in imports: ...

More than one agent file imported Import only one file from .github/agents/ per workflow Compilation Errors Section titled “Compilation Errors” Raised when converting the .md workflow to its .lock.yml . Error Cause Fix workflow file not found: ... Path is wrong or missing Verify the file exists under .github/workflows/ ; run gh aw compile to compile all failed to resolve import '...' Import path or permissions Confirm the file exists relative to repo root and is readable invalid workflowspec: must be owner/repo/path[@ref] Wrong remote import format Use owner/repo/path[@ref] (e.g., github/gh-aw/.github/workflows/shared/example.md@main ) section 'name' not found Referenced section missing Internal processing issue — verify the section exists; report if persistent Runtime Errors Section titled “Runtime Errors” Raised when the compiled workflow executes in GitHub Actions.

Time Delta Errors Section titled “Time Delta Errors” The stop-after and similar fields accept relative deltas ( +24h , +3d , +1d12h30m ) and absolute dates ( 2025-12-31 , December 31, 2025 ). Error Fix invalid time delta format: ... Use supported units: h (minimum), d , w , mo minute unit 'm' is not allowed for stop-after Convert minutes to hours, rounding up (e.g., +2h instead of +90m ) time delta too large: ... Stay within: 12 months, 52 weeks, 365 days, 8760 hours duplicate unit '[unit]' in time delta Combine values for the same unit (e.g., +3d instead of +1d2d ) unable to parse date-time: ...

Use a supported format like 2025-12-31 23:59:59 , December 31, 2025 , or 12/31/2025 Other Runtime Errors Section titled “Other Runtime Errors” Error Fix jq not found in PATH Install jq — Ubuntu/Debian: sudo apt-get install jq ; macOS: brew install jq authentication required Run gh auth login , or ensure GITHUB_TOKEN is available in Actions Engine-Specific Errors Section titled “Engine-Specific Errors” Error Fix manual-approval value must be a string Use a string: manual-approval: "Approve deployment to production" invalid frontmatter key 'triggers:' Use on: instead of triggers: to match standard GitHub Actions syntax — see Triggers invalid on: section format Follow GitHub Actions syntax (e.g., on: push , on: { push: { branches: [main] } } ) File Processing Errors Section titled “File Processing Errors” Error Fix failed to read file ...

Verify the file exists, is readable, and the disk is not full failed to create .github/workflows directory Check filesystem permissions and disk space workflow file '...' already exists. Use --force to overwrite Re-run with --force (e.g., gh aw init my-workflow --force ) MCP Configuration Errors Section titled “MCP Configuration Errors” Error Fix failed to parse existing mcp.json: ... Validate JSON ( cat .github/mcp.json | jq . ) or delete to regenerate failed to marshal mcp.json: ...

Internal error — report with reproduction steps http MCP tool '...' missing required 'url' field Add url: to the HTTP MCP server configuration unable to determine MCP type for tool '...' Specify at least one of type , url , command , or container tool '...' mcp configuration cannot specify both 'container' and 'command' Use either container: or command: , not both tool '...' mcp configuration with type 'http' cannot use 'container' field Remove container: from HTTP MCP servers (only valid for stdio) Strict Mode Errors Section titled “Strict Mode Errors” Strict mode is the default.

To opt out, use gh aw compile without --strict and avoid strict: false in frontmatter — see Strict Mode . Error Fix 'network' configuration is required Add network: defaults , explicit allowed domains, or network: {} to deny all write permission 'contents: write' is not allowed Use safe outputs (e.g., create-issue , create-pull-request ) instead of write permissions wildcard '*' is not allowed in network.allowed domains Use specific domains, wildcard patterns ( *.cdn.example.com ), or ecosystem identifiers ( python , node ) custom MCP server '...' with container must have network configuration Add network: with allowed domains to containerized MCP servers engine does not support firewall Use an engine with firewall support (e.g., copilot ), or remove --strict This workflow is running on a public repository but was not compiled with strict mode.

Recompile with gh aw compile --strict Safe Output & Workflow Errors Section titled “Safe Output & Workflow Errors” Error Fix cannot use 'command' with 'issues' in the same workflow Remove the conflicting event trigger — command: auto-handles these events. Use events: inside the command to restrict scope workflow uses safe-outputs.create-issue but repository ... does not have issues enabled Enable the feature in Settings → General → Features, or use a different safe output job name cannot be empty Internal error — report with your workflow file Toolset Configuration Section titled “Toolset Configuration” Tool Not Found After Migrating to Toolsets Section titled “Tool Not Found After Migrating to Toolsets” The tool may be in a different toolset, or you chose a narrower one.

Check GitHub Toolsets , run gh aw mcp inspect <workflow> to list available tools, then add the required toolset. Invalid Toolset Name Section titled “Invalid Toolset Name” invalid toolset: '...' is not a valid toolset — valid names: context , repos , issues , pull_requests , users , actions , code_security , discussions , labels , notifications , orgs , projects , gists , search , dependabot , experiments , secret_protection , security_advisories , stargazers , default , all .

Toolsets and Allowed Conflict Section titled “Toolsets and Allowed Conflict” When both toolsets: and allowed: are specified, allowed: restricts tools to only those listed within the enabled toolsets. Prefer using only toolsets: : # Recommended tools : github : toolsets : [ issues ] # Advanced: restrict within toolset tools : github : toolsets : [ issues ] allowed : [ create_issue ] GitHub MCP Server Read-Only Enforcement Section titled “GitHub MCP Server Read-Only Enforcement” GitHub MCP server read-only mode cannot be disabled — the GitHub MCP server is always read-only.

Remove read-only: false (or set it to true ). Use safe outputs for write operations. Troubleshooting Tips Section titled “Troubleshooting Tips” Use --verbose for detailed error information Validate YAML syntax and file paths Consult the Frontmatter Reference Compile frequently to catch errors early; use --strict to surface security issues Add features incrementally Getting Help Section titled “Getting Help” If your error isn’t listed: Re-run with gh aw compile --verbose Search this page (Ctrl+F / Cmd+F) for keywords from the error Use an agent with the debug.md prompt to investigate failing runs Review workflow patterns and Common Issues Report the issue on GitHub