Common Issues

This reference documents frequently encountered issues when working with GitHub Agentic Workflows, organized by workflow stage and component.

Installation Issues

Extension Installation Fails

If gh extension install githubnext/gh-aw fails with authentication or permission errors (common in Codespaces outside the githubnext organization), use the standalone installer:

curl -sL https://raw.githubusercontent.com/githubnext/gh-aw/main/install-gh-aw.sh | bash

After installation, the binary is installed to ~/.local/share/gh/extensions/gh-aw/gh-aw and can be used with gh aw commands just like the extension installation.

Extension Not Found After Installation

If you installed the extension but gh aw command is not found:

1. Verify installation: gh extension list
2. If not listed, reinstall: gh extension install githubnext/gh-aw
3. If issues persist, use the standalone installer (see above)

Codespace Authentication Issues

GitHub Codespaces may have limited permissions for installing GitHub CLI extensions. If you encounter authentication errors:

1. Try the standalone installer (recommended for Codespaces)
2. Or grant additional permissions to your Codespace token

Workflow Compilation Issues

Workflow Won’t Compile

If gh aw compile fails, check YAML frontmatter syntax (proper indentation with spaces, colons with spaces after them), verify required fields like on: are present, and ensure field types match the schema. Use gh aw compile --verbose for detailed error messages.

Lock File Not Generated

If .lock.yml isn’t created, fix compilation errors first (gh aw compile 2>&1 | grep -i error) and verify write permissions on .github/workflows/.

Orphaned Lock Files

Remove old .lock.yml files after deleting .md files with gh aw compile --purge.

Import and Include Issues

Import File Not Found

Import paths are relative to repository root. Verify the file exists and is committed (git status). Example paths: .github/workflows/shared/tools.md (from repo root) or shared/security-notice.md (relative to .github/workflows/).

Multiple Agent Files Error

Import only one file from .github/agents/ per workflow. Use other imports for shared content like tools.

Circular Import Dependencies

If compilation hangs, check for import files that import each other. Remove circular references by reviewing the import chain.

Tool Configuration Issues

GitHub Tools Not Available

Configure GitHub tools using toolsets: (recommended) or verify tool names from the tools reference:

tools:
  github:
    toolsets: [repos, issues]  # Recommended: use toolsets

Migrate to Toolsets

If you’re using the allowed: pattern with GitHub tools, consider migrating to toolsets: for better maintainability. Tool names may change between MCP server versions, but toolsets provide a stable API. See Migration from Allowed to Toolsets.

Toolset Missing Expected Tools

If tools you expect are not available after configuring toolsets:

1. Verify the right toolset: Check the toolset contents to find which toolset contains your tool
2. Add additional toolsets: Combine toolsets as needed (e.g., toolsets: [default, actions])
3. Inspect configuration: Run gh aw mcp inspect <workflow> to see available tools

MCP Server Connection Failures

Verify the MCP server package is installed and configuration syntax is valid. Ensure required environment variables are set:

mcp-servers:
  my-server:
    command: "npx"
    args: ["@myorg/mcp-server"]
    env:
      API_KEY: "${{ secrets.MCP_API_KEY }}"

Playwright Network Access Denied

Add blocked domains to the allowed_domains list:

tools:
  playwright:
    allowed_domains: ["github.com", "*.github.io"]

Permission Issues

Write Operations Fail

Grant required permissions in the permissions: section or use safe-outputs (recommended):

# Direct write
permissions:
  contents: read
  issues: write
  pull-requests: write

# Safe-outputs (recommended)
permissions:
  contents: read
safe-outputs:
  create-issue:
  add-comment:

Safe Outputs Not Creating Issues

Disable staged mode to create issues (not just preview):

safe-outputs:
  staged: false
  create-issue:
    title-prefix: "[bot] "
    labels: [automation]

Token Permission Errors

Add permissions to GITHUB_TOKEN or use a custom token:

# Increase GITHUB_TOKEN permissions
permissions:
  contents: write
  issues: write

# Or use custom token
safe-outputs:
  github-token: ${{ secrets.CUSTOM_PAT }}
  create-issue:

Engine-Specific Issues

Copilot CLI Not Found

The compiled workflow should automatically include CLI installation steps. If missing, verify compilation succeeded.

Model Not Available

Use the default model or specify an available one:

engine: copilot  # Default model

# Or specify model
engine:
  id: copilot
  model: gpt-4

Context Expression Issues

Unauthorized Expression

Use only allowed expressions like github.event.issue.number, github.repository, or needs.activation.outputs.text. Expressions like secrets.GITHUB_TOKEN or env.MY_VAR are not allowed.

Sanitized Context Empty

needs.activation.outputs.text is only populated for issue, PR, or comment events (e.g., on: issues:) but not for other triggers like push:.

Build and Test Issues

Documentation Build Fails

Install dependencies, check for malformed frontmatter or MDX syntax, and fix broken links:

cd docs
rm -rf node_modules package-lock.json
npm install
npm run build

Tests Failing After Changes

Format code and check for issues before running tests:

make fmt
make lint
make test-unit

Network and Connectivity Issues

URLs Appearing as “(redacted)”

If URLs in workflow outputs or sanitized content show as (redacted), the domain is not in the allowed list. Content sanitization automatically filters URLs from untrusted domains to prevent data exfiltration.

Add the domain to your workflow’s network: configuration:

network:
  allowed:
    - defaults              # Basic infrastructure
    - "api.example.com"     # Add your domain here

Default allowed domains include GitHub domains (github.com, githubusercontent.com, etc.). For more configuration options, see Network Permissions.

Cannot Download Remote Imports

Verify network access and GitHub authentication:

curl -I https://raw.githubusercontent.com/githubnext/gh-aw/main/README.md
gh auth status

MCP Server Connection Timeout

Use a local MCP server if HTTP connections timeout:

mcp-servers:
  my-server:
    command: "node"
    args: ["./server.js"]

Cache Issues

Cache Not Restoring

Verify cache key patterns match and note that caches expire after 7 days:

cache:
  key: deps-${{ hashFiles('package-lock.json') }}
  restore-keys: deps-

Cache Memory Not Persisting

Configure cache properly for the memory MCP server:

tools:
  cache-memory:
    key: memory-${{ github.workflow }}-${{ github.run_id }}

Debugging Strategies

Enable verbose compilation (gh aw compile --verbose), set ACTIONS_STEP_DEBUG = true for debug logging, inspect generated lock files (cat .github/workflows/my-workflow.lock.yml), check MCP configuration (gh aw mcp inspect my-workflow), and review logs (gh aw logs my-workflow or gh aw audit RUN_ID).

Getting Help

Review reference docs, search existing issues, enable debugging with verbose flags, or create a new issue with reproduction steps. See also: Error Reference and Frontmatter Reference.