Troubleshooting

Symptoms grouped by where they surface. Every entry was observed during deploy-path validation across all eight variants, so the resolutions are field-tested.

Agent container starts but does not connect

Symptom (in agent logs)	Cause	Resolution
FATAL: Missing required environment variables for aws: AWS_ROLE_ARN, AWS_EXTERNAL_ID followed by Agent will stay alive and retry every 60s	Agent thinks it is running outside AWS but no role ARN was provided.	On a Local path, set AWS_ROLE_ARN and AWS_EXTERNAL_ID. On a Cloud path, use agent image v0.7.7 or newer; older images cannot detect they are running on EC2 with an instance profile and insist on the cross-account env vars.
ModuleNotFoundError: No module named 'cache' in a Python traceback	Image is older than v0.7.6 where the cache/ module was first packaged.	Pull :stable (or pin :v0.7.9 or newer).
Failed to persist key at /var/lib/argus/agent.key: PermissionError. Agent will continue in-memory and re-bootstrap on next restart.	Image older than v0.7.9 where /var/lib/argus got the right ownership for the non-root user. The agent works but re-bootstraps every restart, eventually burning the token’s rate-limit quota.	Pull :stable (or pin :v0.7.9 or newer).
botocore.exceptions.NoCredentialsError: Unable to locate credentials while trying to AssumeRole	Local agent has AWS_ROLE_ARN set but the SDK default chain cannot find source credentials.	Export AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY in the shell that runs Docker, or mount ~/.aws into the container.
Bootstrap succeeded but no Authenticated as ... line within 30 seconds	Backend reachable but rejecting the API key.	Almost always a stale persisted key from a deleted-and-recreated cloud account. Remove the named volume (docker compose down -v or docker volume rm argus_agent_data) and start fresh.
Connecting to https://api.argusdspm.com... then network errors	Egress to the backend is blocked.	Check security group egress rules, NAT gateway routing, and DNS resolution.

Cross-account guard rejects jobs

Symptom (in agent logs)	Cause	Resolution
Cross-account guard rejected job: Agent runtime AWS account (NNN) does not match the cloud account this job targets (MMM)	The AWS account the agent process actually runs in (NNN) does not match the external_account_id you registered for this cloud account (MMM).	Edit the cloud account record to use the correct external account ID, or deploy the agent into the right AWS account. The drawer surfaces this as a yellow “cross account mismatch” panel.

Cloud (managed) / Cloud (DIY) deploy fails

Symptom (in CloudFormation or Terraform output)	Cause	Resolution
CloudFormation stack stuck CREATE_IN_PROGRESS past 10 minutes on the AgentInstance resource (EC2 path)	UserData script failed and cfn-signal never reported back. The CreationPolicy timeout is 10 minutes.	SSH or Session Manager into the instance and inspect cat /var/log/cloud-init-output.log plus journalctl -u argus-agent.service.
Fargate task stuck PENDING, then service event says unable to place a task: ResourceInitializationError: failed to create CloudWatch log stream: The specified log group does not exist	The task definition’s awslogs-region does not match the region the log group lives in, OR the execution role’s policy Resource does not cover the log group ARN.	Make awslogs-region match the deploy region. Make the execution-role policy Resource cover the awslogs-group value (e.g. arn:aws:logs:<region>:<account>:log-group:/ecs/argus-agent*).
Fargate task stuck PENDING, then container fails immediately with botocore.exceptions.NoCredentialsError	Task is in a public subnet but assignPublicIp is DISABLED, so the task has no internet route and cannot pull the image or reach AWS endpoints.	Set assignPublicIp=ENABLED (Fargate parameter AssignPublicIp, Terraform assign_public_ip = true), or move to a private subnet with a NAT gateway.
InvalidParameterValue: GroupDescription beyond ASCII when creating a Terraform security group	The deploy-argus module ref you pinned is older than v0.7.7 and contains a non-ASCII character AWS rejects.	Pin the module ref to v0.7.7 or newer.
AccessDeniedException: not authorized to perform: logs:CreateLogGroup on first task run	The execution-role policy’s <LOG_GROUP_ARN_PATTERN> does not match the actual awslogs-group on the task definition.	Widen the policy ARN pattern (e.g. arn:aws:logs:<region>:<account>:log-group:/ecs/*) or align the two names.

Local deploy fails

Symptom	Cause	Resolution
docker compose up exits with services.argus-agent.environment.AWS_ROLE_ARN: required variable AWS_ROLE_ARN not set	.env file is missing or has the wrong variable names.	Create .env next to docker-compose.yml with AWS_ROLE_ARN= and AWS_EXTERNAL_ID= lines.
Container Up and healthy but no scan ever runs	Agent boots but the scan path needs source AWS credentials it cannot find.	See the NoCredentialsError row above.