Guides

Troubleshooting

Common Issues

AWS CLI Access Denied

Symptom: AccessDenied error when running AWS CLI commands.

Solution:

  1. Verify your AWS credentials are configured for the profile you intend to use: 
    aws configure list --profile <your-profile>
  2. Ensure the AWS_PROFILE environment variable is exported in the shell where you run manifest-installer: 
    export AWS_PROFILE=<your-profile>
  3. If the credentials were issued some time ago, contact Manifest Cyber to confirm they have not been rotated.

Error Saving Docker Credentials

Symptom: error saving credentials: error storing credentials after running aws ecr get-login-password ... | docker login ....

Solution:

  1. Remove the Docker config file at ~/.docker/config.json.
  2. Re-run the Docker login: 
    aws ecr get-login-password --region us-east-1 \
  | docker login --username AWS --password-stdin 623542229617.dkr.ecr.us-east-1.amazonaws.com

Image Pull Backoff (ImagePullBackOff)

Symptom: Pods stuck in ImagePullBackOff partway through installation.

Cause: ECR auth tokens expire 12 hours after they are issued.

Solution: Re-run the aws ecr get-login-password ... | docker login ... command, then re-run manifest-installer upgrade --to <version> to resume.

Docker Permission Denied

Symptom: permission denied error when running Docker commands.

Solution: Add your user to the docker group, then log out and back in:

sudo usermod -aG docker $USER

SSH or Sudo Failures During Install

Symptom: Ansible fails connecting to the host or escalating privileges.

manifest-installer uses Ansible to configure the host, which requires SSH access (typically to localhost) and passwordless sudo for the user running the installer.

Solution:

  1. Verify SSH is running and reachable: 
    ssh <ssh-user>@localhost true
  2. Confirm the user has passwordless sudo: 
    sudo -n true
  3. Verify SSH key permissions if you are using key-based auth: 
    chmod 600 ~/.ssh/id_rsa

Wizard Bails Mid-Installation

Symptom: The wizard exits with an error during manifest-installer upgrade.

Solution: The upgrade is idempotent. Re-run the same command and it will resume from the saved state:

manifest-installer upgrade --to <version>

If you want to start over, recreate the deployment (this backs up and replaces the deployment directory):

manifest-installer init --recreate --yes --version <version>

Inspect or Manually Operate on the Deployment

For ad-hoc debugging, drop into a shell inside the install-tools container with the deployment directory mounted:

manifest-installer shell

To see what version is deployed and the current wizard state:

manifest-installer status

Support

For additional assistance, contact Manifest Cyber support:

Related Documentation

Updated 5 days ago