How to Troubleshoot Common agents-cli Deployment Failures (Cloud Run, GKE, Agent Runtime)

Most agents-cli deployment failures stem from missing Dockerfiles, ignore-file conflicts, reserved environment variables, or IAM permission gaps, all of which surface with explicit error messages in agent_runtime.py before the build starts.

The google/agents-cli tool unifies deployment across Cloud Run, GKE, and Vertex AI Agent Runtime through a shared workflow implemented in src/google/agents/cli/deploy/agent_runtime.py. While the CLI abstracts containerization and orchestration complexity, failures typically occur during the validation, packaging, or IAM provisioning phases. Understanding the specific checks in the source code allows you to diagnose and resolve agents-cli deployment failures without waiting for long-running operations to timeout.

The Core Deployment Workflow

All three targets follow the same high-level sequence defined in the CLI core:

1. Validate the project scaffold (Dockerfile, ignore files, environment configuration).
2. Build a package list (files shipped to the service).
3. Create or update the remote resource (Cloud Run service, GKE deployment, or Agent Engine).
4. Poll the long-running operation and write a metadata file for status checks.

Because the implementation shares logic across platforms, troubleshooting agents-cli deployment failures follows consistent patterns regardless of whether you deploy to Cloud Run, GKE, or Agent Runtime.

Missing or Excluded Dockerfile Errors

Agent Runtime and Cloud Run both require a container image, which necessitates a Dockerfile in the project root. The CLI performs an explicit existence check early in the deployment process:

if not os.path.exists("Dockerfile"):
    raise click.ClickException(_missing_dockerfile_error(cfg))

Source: src/google/agents/cli/deploy/agent_runtime.py

If the file exists but is excluded by .gcloudignore or .gitignore, the packaging step silently omits it, triggering a secondary validation failure:

if auto_packaged and "./Dockerfile" not in source_packages:
    raise click.ClickException(
        "Dockerfile is present but excluded by .gcloudignore/.gitignore.\n"
        "  Remove the matching ignore pattern so the deploy can package it."
    )

Source: src/google/agents/cli/deploy/agent_runtime.py

Fix: Run agents-cli scaffold create to regenerate the Dockerfile, or manually add one. Then verify that .gcloudignore and .gitignore do not contain patterns matching Dockerfile.

Reserved Environment Variable Conflicts

The platform automatically injects GOOGLE_CLOUD_PROJECT. Supplying this variable in your .env file or via --set-env-vars causes the CLI to strip it and emit a warning:

for reserved in _AGENT_RUNTIME_RESERVED_ENV & env_vars.keys():
    logging.warning(
        "Ignoring reserved Agent Runtime env var %s — it is set by the platform.",
        reserved,
    )
    del env_vars[reserved]

Source: src/google/agents/cli/deploy/agent_runtime.py

Fix: Remove GOOGLE_CLOUD_PROJECT from your environment configuration. The CLI handles project identification automatically.

Invalid Region Specification

Agent Runtime does not support the pseudo-region global. Attempting to use it triggers an immediate validation error:

if location == "global":
    raise click.ClickException(
        "Region 'global' is not supported for Agent Runtime deployments.\n"
        "  Please specify a regional location (e.g., 'us-central1', 'us-east1') ..."
    )

Source: src/google/agents/cli/deploy/agent_runtime.py

Fix: Specify a valid region such as us-east1 or europe-west1 using the --region flag or set it in pyproject.toml.

IAM Permission and Identity Errors

When using --agent-identity, the CLI attempts to bind specific IAM roles to the service identity. The code enumerates required roles and applies them via set_iam_policy:

roles = [
    "roles/aiplatform.user",
    "roles/serviceusage.serviceUsageConsumer",
    "roles/browser",
    "roles/cloudapiregistry.viewer",
    "roles/logging.logWriter",
    "roles/monitoring.metricWriter",
]
principal = f"principal://{agent.api_resource.spec.effective_identity}"

# ...

proj_client.set_iam_policy(
    request=iam_policy_pb2.SetIamPolicyRequest(
        resource=f"projects/{project}", policy=policy
    )
)

Source: src/google/agents/cli/deploy/agent_runtime.py

Fix: Ensure your account has iam.roles.admin on the project. If you encounter "permission denied" errors, request a project owner to grant the missing roles or remove the --agent-identity flag to use the default compute service account.

Secret Management Mistakes

Secrets must be passed via --set-secrets using the format ENV_VAR=SECRET_ID[:VERSION]. The parsing logic in _utils.py converts these strings into the API structure:

def parse_secrets(secrets_string: str | None) -> dict[str, dict[str, str]]:
    raw = parse_key_value_pairs(secrets_string)
    # ...

    result[key] = {"secret": secret_id, "version": version}

Source: src/google/agents/cli/deploy/agent_runtime.py and src/google/agents/cli/scaffold/utils/_utils.py

Common failure modes include:

• Invalid format: Use the full resource path: projects/PROJECT/locations/REGION/secrets/NAME[:VERSION].
• Plain text exposure: Passing secrets via --set-env-vars instead of --set-secrets prevents masking in logs.
• Update residue: When updating, existing secrets merge with new ones. To clear all secrets, pass --set-secrets= (empty string).

Interrupted Operations and Status Recovery

Network interruptions or Ctrl-C during deployment do not abort the remote operation. The CLI persists the operation ID in .agents-cli/operation.json. Resume monitoring with:

agents-cli deploy --status

The status routine reads the metadata file and polls the long-running operation:

# Simplified representation of the status check logic

operation = operations_client.get_operation(name=operation_name)
if operation.done:
    print_final_status(operation)
else:
    print_progress(operation)

Source: src/google/agents/cli/deploy/agent_runtime.py

Fix: Run agents-cli deploy --status repeatedly until the operation completes. Inspect the resulting metadata file to retrieve the deployed resource name.

Resource Limit Mismatches

When updating resource limits, providing only --cpu or only --memory can cause specification conflicts. The CLI prevents this by copying the missing value from the live resource:

if (cpu is None) ^ (memory is None):
    # fetch existing limits from live resource

    cpu = cpu if cpu is not None else existing_cpu
    memory = memory if memory is not None else existing_memory

Source: src/google/agents/cli/deploy/agent_runtime.py

Fix: Supply both --cpu and --memory together when changing limits, or allow the CLI to preserve the existing pair automatically.

Summary

• Validate Dockerfile presence: Ensure Dockerfile exists and is not excluded by .gcloudignore or .gitignore.
• Avoid reserved variables: Remove GOOGLE_CLOUD_PROJECT from .env and --set-env-vars.
• Use regional locations: Never specify global for Agent Runtime deployments.
• Check IAM permissions: Verify iam.roles.admin when using --agent-identity.
• Format secrets correctly: Use --set-secrets with full resource paths, not --set-env-vars.
• Recover from interruptions: Use agents-cli deploy --status to resume monitoring after disconnections.
• Update limits symmetrically: Provide both --cpu and --memory or neither when modifying resource constraints.

Frequently Asked Questions

Why does agents-cli fail with "Dockerfile not found" even though the file exists?

The file is likely excluded by your .gcloudignore or .gitignore. According to the source code in agent_runtime.py, the CLI checks for ./Dockerfile in the packaged source list after applying ignore rules. Remove any pattern matching Dockerfile from these ignore files and redeploy.

Can I use the global region for Agent Runtime deployments?

No. The agent_runtime.py source explicitly rejects global as a valid location for Agent Runtime, requiring a specific regional endpoint like us-central1 or europe-west4. Cloud Run and GKE may have different region requirements, but Agent Runtime strictly requires regional specificity.

How do I recover if my deployment command is interrupted?

The operation continues server-side even if your terminal disconnects. Run agents-cli deploy --status to reconnect to the long-running operation stored in .agents-cli/operation.json. This polls the current state and prints the final resource URL once the deployment completes.

What IAM roles are required for the --agent-identity feature?

The CLI attempts to grant roles/aiplatform.user, roles/serviceusage.serviceUsageConsumer, roles/browser, roles/cloudapiregistry.viewer, roles/logging.logWriter, and roles/monitoring.metricWriter to the service identity principal. Your user account must possess iam.roles.admin on the project to perform these bindings, or the deployment will fail during the identity provisioning phase.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}