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

> Troubleshoot common agents-cli deployment failures on Cloud Run and GKE. Learn to fix Dockerfile issues, ignore-file conflicts, environment variable conflicts, and IAM permission gaps quickly.

- Repository: [Google/agents-cli](https://github.com/google/agents-cli)
- Tags: how-to-guide
- Published: 2026-07-02

---

**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`](https://github.com/google/agents-cli/blob/main/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`](https://github.com/google/agents-cli/blob/main/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:

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

```

*Source:* [`src/google/agents/cli/deploy/agent_runtime.py`](https://github.com/google/agents-cli/blob/main/src/google/agents/cli/deploy/agent_runtime.py#L1518-L1522)

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

```python
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`](https://github.com/google/agents-cli/blob/main/src/google/agents/cli/deploy/agent_runtime.py#L1520-L1524)

**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:

```python
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`](https://github.com/google/agents-cli/blob/main/src/google/agents/cli/deploy/agent_runtime.py#L1223-L1227)

**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:

```python
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`](https://github.com/google/agents-cli/blob/main/src/google/agents/cli/deploy/agent_runtime.py#L4049-L4056)

**Fix:** Specify a valid region such as `us-east1` or `europe-west1` using the `--region` flag or set it in [`pyproject.toml`](https://github.com/google/agents-cli/blob/main/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`:

```python
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`](https://github.com/google/agents-cli/blob/main/src/google/agents/cli/deploy/agent_runtime.py#L2929-L2960)

**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`](https://github.com/google/agents-cli/blob/main/_utils.py) converts these strings into the API structure:

```python
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`](https://github.com/google/agents-cli/blob/main/src/google/agents/cli/deploy/agent_runtime.py#L69-L79) and [`src/google/agents/cli/scaffold/utils/_utils.py`](https://github.com/google/agents-cli/blob/main/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`](https://github.com/google/agents-cli/blob/main/.agents-cli/operation.json). Resume monitoring with:

```bash
agents-cli deploy --status

```

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

```python

# 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`](https://github.com/google/agents-cli/blob/main/src/google/agents/cli/deploy/agent_runtime.py#L3871-L3890)

**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:

```python
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`](https://github.com/google/agents-cli/blob/main/src/google/agents/cli/deploy/agent_runtime.py#L4930-L5068)

**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`](https://github.com/google/agents-cli/blob/main/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`](https://github.com/google/agents-cli/blob/main/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`](https://github.com/google/agents-cli/blob/main/.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.