Troubleshoot a failed deployment

GENI never has console access to your AWS account or GCP project. When an environment, engine, or queue gets stuck in FAILED or DELETE_FAILED, the status/error fields on geni environment get/geni engine get/geni queue get only tell you the deployment failed — not which resource, or why. revisions and logs show the underlying CloudFormation stack events (AWS) or Terraform apply errors (GCP) for the failed operation, straight from the GENI database.

Revisions

A stack is created once and can be updated many times — every create, update, or delete is a revision, numbered from 1. revisions lists them newest first:

geni engine revisions <engine-id>

Revision  Action  Status    Started              Finished             Events  Reason
2         UPDATE  FAILED    2026-08-07 14:02:10  2026-08-07 14:03:41  6       UPDATE_ROLLBACK_COMPLETE: ...
1         CREATE  COMPLETE  2026-08-07 09:15:02  2026-08-07 09:19:47  14

The same command works for geni environment revisions <id> and geni queue revisions <id>.

Note

Revisions are collected once, when a deployment operation finishes — this is a read of GENI’s own database, not a live call to your cloud account. A stack that was created before this feature shipped has no revisions until the next time it’s updated or deleted.

Logs

logs shows the events belonging to one revision — defaults to the latest:

geni engine logs <engine-id>
geni engine logs <engine-id> --revision 1

Timestamp            Status               Type                          Logical ID       Reason
2026-08-07 14:03:41  UPDATE_ROLLBACK_COMPLETE  AWS::CloudFormation::Stack   geni-engine-ab12cd
2026-08-07 14:03:22  UPDATE_FAILED        AWS::Batch::ComputeEnvironment  ComputeEnvironment  CLIENT_ERROR: ...

On GCP, a failed revision also prints the Terraform error log beneath the table.

Same commands for geni environment logs <id> and geni queue logs <id> — with one exception: GCP queues hold no cloud resources (the queue record itself is the queue, read directly by the submission path), so geni queue logs on a GCP queue always reports unavailable.

Common failure signatures

Symptom in logs	Likely cause
INSUFFICIENT_CAPABILITIES or CREATE_FAILED on an IAM resource	The cross-account role from geni setup create is missing a permission — re-run geni setup create to pick up policy updates
RESOURCE_LIMIT_EXCEEDED / quota errors on a VPC, EIP, or Batch compute environment	AWS account or GCP project quota reached in that region — request a quota increase
A subnet or CIDR conflict on environment create	The region already has a conflicting VPC/CIDR range from unrelated infrastructure
GCP PERMISSION_DENIED referencing an API	A required API isn’t enabled yet — see Enable a GCP project
UPDATE_ROLLBACK_COMPLETE after geni engine update/geni environment update	The update failed and CloudFormation rolled back automatically — the entity is back to its previous working state; check logs --revision <n> for the specific resource that failed

If none of these match, geni engine logs <id> (or environment/queue) is still the fastest way to hand support the exact resource and error text.