FAQ and Troubleshooting

This page describes the most common issues when creating and running Agents.

The Agent won't launch

Possible causes:

• The task goal is empty or too short.
• Necessary resources aren't connected.
• The budget hasn't been set.
• The Agent role is empty.
• Git or cloud authorization failed.
• The approval policy is missing.

How to handle it:

1. Add more detail to the task goal.
2. Open the preparation checklist.
3. Connect the missing resources.
4. Re-confirm the Agent roles.
5. Set the budget.
6. Launch again.

The task is stuck in preparing

Possible causes:

• Resource discovery is slow.
• SK snapshot parsing failed.
• The cloud resource API timed out.
• The secret vault is unavailable.
• The Agent platform is queued.

How to handle it:

• Check the preparation checklist status.
• Check recent events.
• Re-parse the SK.
• Check resource authorization.
• Retry later.
• Contact the administrator to check platform status.

The task shows "needs input"

The task itself is still running, but the Agent triggered a task.blocked event, meaning the Agent can't decide how to continue.

Common issues:

• The requirements have multiple possible directions.
• The resource scope is unclear.
• An approach needs to be chosen.
• A test account is missing.
• A deployment target is missing.

How to handle it:

• Open the task details.
• Read the question.
• Give a clear choice.
• Don't just reply "continue."

Awaiting approval

The task is still running, but there's an approval request in the pending state, meaning the Agent requested a high-risk operation.

How to handle it:

1. Check the operation type.
2. Check the requesting Agent.
3. Check the target resource.
4. Check the risk level and credential TTL.
5. Approve or reject.

If unsure, reject and ask the Agent to produce a more detailed plan.

Git authorization failed

Possible causes:

• The token has expired.
• Insufficient repository permissions.
• The branch doesn't exist.
• The path scope is too narrow.
• Organization policy disallows access.

How to handle it:

• Re-authorize Git.
• Check repository permissions.
• Choose the correct branch.
• Adjust the path scope.
• Contact the organization administrator.

SK parsing failed

Possible causes:

• The SK repository is inaccessible.
• The ref doesn't exist.
• SKILL.md is missing.
• The skill declaration format is wrong.
• The skill requested a disallowed tool.

How to handle it:

• Choose an accessible SK repository.
• Pin to a valid tag or commit.
• Fix SKILL.md.
• Disable the dangerous skill.
• Re-parse the snapshot.

Cloud resource inaccessible

Possible causes:

• The cloud authorization expired.
• The resource is outside the authorized scope.
• The wrong environment was selected.
• Approval is required.
• The short-lived credential expired.

How to handle it:

• Reconnect the cloud account.
• Adjust the resource scope.
• Re-approve.
• Re-derive a short-lived credential.
• Check the cloud platform status.

Budget exhausted

Possible causes:

• The task scope is too large.
• Repeated retries after failure.
• A high-cost model was used.
• Multiple Agents executed in parallel.

How to handle it:

• Pause the task.
• Review the consumption breakdown.
• Narrow the scope.
• Split the task.
• Adjust the model strategy.
• Raise the budget and continue.

Task failed

Handling order:

1. Check the failure reason.
2. Check recent logs.
3. Check resource access records.
4. Check whether an approval was rejected.
5. Check whether the budget ran out.
6. Check test or build output.
7. Ask the Agent to summarize a recoverable approach.

Suspected secret leak

Handle immediately:

1. Stop the task.
2. Revoke the relevant credentials.
3. Rotate the secret.
4. Check Git, logs, Markdown, and screenshots.
5. Notify the security lead.
6. Check the audit trail.
7. Re-authorize before continuing.

The delivered result doesn't meet expectations

How to handle it:

• Compare against the acceptance criteria.
• Point out clearly what doesn't match.
• Ask the Agent to fix only the specified issue.
• Don't expand the task's scope.
• Roll back to the planning stage if necessary.

Example:

The current result doesn't meet acceptance criterion #2.
Please only fix the empty project list issue after user login.
Don't modify the notifications module.
When done, run the existing tests and give me a diff summary.