Common Issues

Pipeline Compilation Errors

”Source markdown not found”

The check command couldn’t locate the source .md file referenced in the compiled pipeline’s @ado-aw header.

Solution: Ensure the markdown source file hasn’t been moved or renamed since compilation. Recompile with ado-aw compile.

Front matter parse errors

YAML front matter must be valid YAML between --- delimiters.

Common causes:

• Unquoted strings containing special YAML characters (:, #, {, })
• Incorrect indentation (YAML uses spaces, not tabs)
• Missing required fields (name, description)

---
# ✗ Bad -- colon in unquoted string
description: Agent: does things

# ✓ Good -- quoted string
description: "Agent: does things"
---

“Deprecated front-matter shapes”

ado-aw check may print:

contains deprecated front-matter shapes that need codemod fixes.
hint: run `ado-aw compile <file>` to apply the codemods in place.

Solution: Run ado-aw compile ./agent.md. The compiler detects the old shape, rewrites the source file in place, and prints which codemods fired. Once compilation succeeds, commit the updated front matter. See the codemods reference for details.

”Safe outputs require write access to ADO, but no write service connection is configured”

(Historical error — no longer emitted.) Earlier versions of ado-aw hard-failed compilation when a write-bearing safe-output (e.g. create-pull-request, create-work-item, add-pr-comment) was configured without permissions.write. The compiler now defaults the Stage 3 executor to $(System.AccessToken) and no longer requires permissions.write for these tools.

If you’re hitting this from an older release, upgrade ado-aw. If you genuinely need ARM-minted write tokens (for cross-org writes or named-identity attribution), see the Service Connections guide.

”safe-outputs contains unrecognised tool name(s)”

A key under safe-outputs: does not match any known tool name. The compiler now rejects unknown keys rather than silently dropping them.

safe-outputs contains unrecognised tool name(s):
  - create-pr (similar known tools: create-branch, create-git-tag, create-pull-request, create-wiki-page, create-work-item)

Valid safe-output keys are listed in docs/safe-outputs.md. Each key must
match exactly the kebab-case name registered by a tool in src/safeoutputs/
(e.g. `create-pull-request`, not `create-pr`).

Solution: Replace the unrecognised key with the correct tool name shown in the “similar known tools” hint. All tool names use kebab-case and must match exactly:

# ✗ Bad — old short-form that used to be silently dropped
safe-outputs:
  create-pr:
    target-branch: main

# ✓ Good — exact registered name
safe-outputs:
  create-pull-request:
    target-branch: main

See the Safe Outputs reference for the full list of available tool names.

”safe-outputs contains tool name(s) with invalid characters”

A key under safe-outputs: contains characters other than ASCII letters, digits, and hyphens.

Solution: Use only lowercase letters, digits, and hyphens in safe-outputs: keys:

# ✗ Bad — spaces are not allowed
safe-outputs:
  create work item: {}

# ✓ Good
safe-outputs:
  create-work-item: {}

“safe-outputs.comment-on-work-item requires a ‘target’ field”

Certain safe-output tools require an explicit target: in the front matter configuration. comment-on-work-item and update-work-item are the most common examples — they need target: to scope which work items can be modified.

Solution: Add a target: field under the tool’s safe-outputs: entry:

safe-outputs:
  comment-on-work-item:
    max: 3
    target: "*"   # any work item, or a specific ID / area path prefix

Runtime Errors

Network timeouts in AWF sandbox

The agent can only access explicitly allowed domains. If your agent needs to reach an external service:

1. Check if a runtime enables the domain — for example, runtimes: python: true adds pypi.org and other Python ecosystem hosts.

2. Add custom domains explicitly under network: allowed: in the front matter:

   network:
     allowed:
       - "api.contoso.internal"
       - "*.packages.example.com"

3. For Azure DevOps API access (work items, PRs, repos), configure a service connection under permissions: — that’s separate from network domain access.

Safe output validation failures

Stage 2 (Detection) may reject safe outputs that appear to contain:

• Prompt injection patterns
• Embedded secrets or tokens
• Malformed parameters

Solution: Review the agent’s output proposals. Ensure generated content doesn’t accidentally include patterns that resemble secrets (long base64 strings, key-value patterns matching password=...).

Stage 3 SafeOutputs fails with HTTP 403 / TF401027

The Stage 3 executor uses $(System.AccessToken) by default, which represents one of two ADO-minted build-service identities (collection-scoped or project-scoped) depending on the “Limit job authorization scope to current project” setting. If that identity lacks PullRequestContribute / GenericContribute / CreateBranch (or, worse, has an explicit Deny) on the target repo, every safe output that touches PRs, branches, or pushes fails with TF401027.

See the dedicated Safe-output 401/403 errors page for the full diagnosis flow, a permission bitmask decoder, a REST recipe for inspecting the ACEs, and the three fix paths (write service connection / flip the auth-scope toggle / lift the Deny).

Build & Development

cargo build fails with missing dependencies

Ensure you’re using the Rust 2024 edition toolchain:

rustup update
rustup default stable

cargo test hangs

Some tests require shellcheck to be installed. If missing, tests are skipped (unless ENFORCE_BASH_LINT=1 is set).

# macOS
brew install shellcheck

# Ubuntu/Debian
sudo apt-get install -y shellcheck

Getting Help

If your issue isn’t covered here:

1. Check the GitHub Issues
2. Review the Reference documentation for field specifications
3. Run with --debug for verbose logging: ado-aw --debug compile ./agent.md