This reference documents common error messages encountered when working with GitHub Agentic Workflows, organized by when they occur during the workflow lifecycle.

Schema validation errors occur when the workflow frontmatter does not conform to the expected JSON schema. These errors are detected during the compilation process.

frontmatter not properly closed

The YAML frontmatter section lacks a closing --- delimiter. Ensure the frontmatter is enclosed between two --- lines:

---
on: push
permissions:
  contents: read
---
# Workflow content

failed to parse frontmatter: [yaml error details]

Invalid YAML syntax in the frontmatter. Check indentation (use spaces, not tabs), ensure colons are followed by spaces, quote strings with special characters, and verify array/object syntax:

# Correct indentation and spacing
on:
  issues:
    types: [opened]

timeout-minutes must be an integer

A field received a value of the wrong type. Use the correct type as specified in the frontmatter reference (e.g., timeout-minutes: 10 not "10").

Unknown property: permisions. Did you mean 'permissions'?

Use the suggested field name from the error message. The compiler uses fuzzy matching to suggest corrections for common typos.

imports field must be an array of strings

The imports: field must use array syntax:

imports:
  - shared/tools.md
  - shared/security.md

multiple agent files found in imports: 'file1.md' and 'file2.md'. Only one agent file is allowed per workflow

Import only one agent file per workflow from .github/agents/.

Compilation errors occur when the workflow file is being converted to a GitHub Actions YAML workflow (.lock.yml file).

workflow file not found: [path]

Verify the file exists in .github/workflows/ and the filename is correct. Use gh aw compile without arguments to compile all workflows in the directory.

failed to resolve import 'path': [details]

Ensure the imported file exists at the specified path (relative to repository root) and has read permissions.

invalid workflowspec: must be owner/repo/path[@ref]

Use the correct format for remote imports: owner/repo/path[@ref] (e.g., github/gh-aw/.github/workflows/shared/example.md@main).

section 'name' not found

Verify the referenced section exists in the frontmatter. This typically occurs during internal processing and may indicate a bug.

Runtime errors occur when the compiled workflow executes in GitHub Actions.

invalid time delta format: +[value]. Expected format like +25h, +3d, +1w, +1mo, +1d12h30m

Use the correct time delta syntax with supported units: h (hours, minimum), d (days), w (weeks), mo (months). Example: stop-after: +24h.

minute unit 'm' is not allowed for stop-after. Minimum unit is hours 'h'. Use +[hours]h instead of +[minutes]m

Convert minutes to hours (round up as needed). Use +2h instead of +90m.

time delta too large: [value] [unit] exceeds maximum of [max]

Reduce the time delta or use a larger unit. Maximum values: 12 months, 52 weeks, 365 days, 8760 hours.

duplicate unit '[unit]' in time delta: +[value]

Combine values for the same unit (e.g., +3d instead of +1d2d).

unable to parse date-time: [value]. Supported formats include: YYYY-MM-DD HH:MM:SS, MM/DD/YYYY, January 2 2006, 1st June 2025, etc

Use a supported date format like "2025-12-31 23:59:59", "December 31, 2025", or "12/31/2025".

jq not found in PATH

Install jq: Ubuntu/Debian: sudo apt-get install jq, macOS: brew install jq.

authentication required

Authenticate with GitHub CLI (gh auth login) or ensure GITHUB_TOKEN is available in GitHub Actions.

manual-approval value must be a string

Use a string value: manual-approval: "Approve deployment to production".

invalid frontmatter key 'triggers:' — use 'on:' to define workflow triggers

Agentic workflow files use on: (not triggers:) to define workflow trigger events, matching standard GitHub Actions syntax. Replace triggers: with on::

---
on:
  issues:
    types: [opened]
permissions:
  contents: read
---

See Triggers for the full list of supported trigger events.

invalid on: section format

Verify the trigger configuration follows GitHub Actions syntax (e.g., on: push, on: { push: { branches: [main] } }).

failed to read file [path]: [details]

Verify the file exists, has read permissions, and the disk is not full.

failed to create .github/workflows directory: [details]

Check file system permissions and available disk space.

workflow file '[path]' already exists. Use --force to overwrite

Use gh aw init my-workflow --force to overwrite.

failed to parse existing mcp.json: [details]

Fix the JSON syntax (validate with cat .vscode/mcp.json | jq .) or delete the file to regenerate.

failed to marshal mcp.json: [details]

Internal error when generating the MCP configuration. Report the issue with reproduction steps.

This section documents the most common errors you may encounter when working with GitHub Agentic Workflows.

cannot use 'command' with 'issues' in the same workflow

Remove the conflicting event trigger (issues, issue_comment, pull_request, or pull_request_review_comment). The command: configuration automatically handles these events. To restrict to specific events, use the events: field within the command configuration.

strict mode: 'network' configuration is required

Add network configuration: use network: defaults (recommended), specify allowed domains explicitly, or deny all network access with network: {}.

strict mode: write permission 'contents: write' is not allowed

Use safe-outputs instead of write permissions. Configure safe outputs like create-issue or create-pull-request with appropriate options.

strict mode: wildcard '*' is not allowed in network.allowed domains

Replace the standalone * wildcard with specific domains, wildcard patterns (e.g., *.cdn.example.com), or ecosystem identifiers (e.g., python, node). Alternatively, use network: defaults.

http MCP tool 'my-tool' missing required 'url' field

Add the required url: field to the HTTP MCP server configuration.

job name cannot be empty

Internal error. Report it with your workflow file.

unable to determine MCP type for tool 'my-tool': missing type, url, command, or container

Specify at least one of: type, url, command, or container.

tool 'my-tool' mcp configuration cannot specify both 'container' and 'command'

Use either container: OR command:, not both.

tool 'my-tool' mcp configuration with type 'http' cannot use 'container' field

Remove the container: field from HTTP MCP server configurations (only valid for stdio-based servers).

strict mode: custom MCP server 'my-server' with container must have network configuration

Add network configuration with allowed domains to containerized MCP servers in strict mode.

workflow uses safe-outputs.create-issue but repository owner/repo does not have issues enabled

Enable the required repository feature (Settings → General → Features) or use a different safe output type.

strict mode: engine does not support firewall

Use an engine with firewall support (e.g., copilot), compile without --strict flag, or use network: defaults.

After changing from allowed: to toolsets:, expected tools are not available. The tool may be in a different toolset than expected, or a narrower toolset was chosen.

Check the GitHub Toolsets documentation, use gh aw mcp inspect <workflow> to see available tools, then add the required toolset.

invalid toolset: 'action' is not a valid toolset

Use valid toolset 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.

Unexpected tool availability when using both toolsets: and allowed:. When both are specified, allowed: restricts tools to only those listed within the enabled toolsets.

For most use cases, use only toolsets: without allowed::

# Recommended: use only toolsets
tools:
  github:
    toolsets: [issues]  # Gets all issue-related tools
# Advanced: restrict within toolset
tools:
  github:
    toolsets: [issues]
    allowed: [create_issue]  # Only create_issue from issues toolset

GitHub MCP server read-only mode cannot be disabled

The GitHub MCP server always operates in read-only mode. Setting read-only: false is not permitted and causes a compilation error:

# Not allowed — causes a compilation error
tools:
  github:
    read-only: false

Remove read-only: false or change it to read-only: true (the default). Write operations should use safe outputs instead of granting the agent direct write access.

• Use --verbose flag for detailed error information
• Validate YAML syntax and check file paths
• Consult the frontmatter reference
• Run gh aw compile frequently to catch errors early
• Use --strict flag to catch security issues early
• Test incrementally: add one feature at a time

If you encounter an error not documented here, search this page (Ctrl+F / Cmd+F) for keywords, review workflow examples in the documentation, enable verbose mode with gh aw compile --verbose, or report issues on GitHub. See Common Issues for additional help.