Skip to content
credctl

Troubleshooting

Search for your error message below, or browse by category. If your error is not listed, open a GitHub issue.

Installation errors

”credctl: command not found”

Cause: credctl binary is not in your PATH.

Solution:

If you installed via Homebrew, restart your shell:

Terminal window
exec $SHELL

If you installed from GitHub Releases, add the binary location to your PATH:

Terminal window
echo 'export PATH="/Applications/credctl.app/Contents/MacOS:$PATH"' >> ~/.zshrc
source ~/.zshrc

macOS Gatekeeper blocks the binary

Cause: The binary was downloaded from GitHub Releases and macOS has not verified the signature.

Solution: Right-click the application, select Open, then click Allow in the dialogue. Alternatively, use the Homebrew installation method which handles signing automatically.

Initialisation errors

”Secure Enclave is not available on this device”

Cause: Running on a Mac without a Secure Enclave (pre-2016 Intel Mac) or a non-macOS platform.

Solution: credctl requires macOS with a Secure Enclave:

  • Apple Silicon Macs (M1, M2, M3, M4)
  • Intel Macs with T2 chip (MacBook Pro 2018+, MacBook Air 2018+, Mac mini 2018, iMac Pro, Mac Pro 2019)

“Device identity already exists.”

Cause: Running credctl init when a key already exists in the Secure Enclave.

Solution: Check your existing identity with credctl status. To replace it, use --force:

Terminal window
credctl init --force

”failed to create config directory”

Cause: Permission issue creating ~/.credctl/.

Solution: Check that your home directory is writable and that ~/.credctl/ does not already exist as a file:

Terminal window
ls -la ~/.credctl

If it exists as a file, remove it and re-run credctl init.

Authentication errors

”device not initialised — run ‘credctl init’ first”

Cause: Running credctl auth before credctl init, or ~/.credctl/config.json is missing or empty.

Solution:

Terminal window
credctl init
credctl setup aws --policy-arn arn:aws:iam::123456789012:policy/YourPolicy

“AWS not configured — run ‘credctl setup aws’ or configure manually”

Cause: The aws block in ~/.credctl/config.json is missing or incomplete.

Solution:

Terminal window
credctl setup aws --policy-arn arn:aws:iam::123456789012:policy/YourPolicy

Or manually add role_arn, issuer_url, region, and s3_bucket to the aws block in ~/.credctl/config.json. See the configuration reference.

”assume role” error (access denied on AssumeRoleWithWebIdentity)

Cause: The IAM role trust policy does not reference the OIDC provider, the audience does not match, or the OIDC documents are not published.

Solution:

  1. Verify OIDC documents are accessible at the issuer URL:

    Terminal window
    curl $(cat ~/.credctl/config.json | python3 -c "import sys,json; print(json.load(sys.stdin)['aws']['issuer_url'])")/.well-known/openid-configuration

  2. Check the IAM role trust policy references the correct OIDC provider ARN in the AWS Console.

  3. Re-publish OIDC documents if needed:

    Terminal window
    credctl oidc publish --bucket $(cat ~/.credctl/config.json | python3 -c "import sys,json; print(json.load(sys.stdin)['aws']['s3_bucket'])")

Touch ID authentication failed

Cause: You cancelled the Touch ID prompt, or Touch ID is not available (lid closed, external keyboard without Touch ID).

Solution: Retry the command and approve the Touch ID prompt. macOS falls back to password entry if Touch ID is unavailable.

CloudFormation deployment errors

”CloudFormation deploy failed”

Cause: Insufficient IAM permissions or resource conflicts.

Solution: You need permissions to create:

  • CloudFormation stacks
  • S3 buckets
  • CloudFront distributions
  • IAM OIDC providers
  • IAM roles

Check the CloudFormation events in the AWS Console for the specific error message.

”S3 bucket already exists”

Cause: S3 bucket names are globally unique. Another account owns a bucket with the same name.

Solution: Use a custom stack name to generate a different bucket name:

Terminal window
credctl setup aws --policy-arn arn:aws:iam::123456789012:policy/YourPolicy --stack-name credctl-myname

OIDC document errors

”OIDC files not found — run ‘credctl oidc generate’ first”

Cause: Running credctl oidc publish before generating OIDC documents.

Solution:

Terminal window
credctl oidc generate --issuer-url https://your-cloudfront-url.cloudfront.net
credctl oidc publish --bucket your-bucket-name

Configuration errors

”failed to read config”

Cause: ~/.credctl/config.json is malformed JSON or has incorrect permissions.

Solution: Check the file is valid JSON:

Terminal window
python3 -m json.tool ~/.credctl/config.json

Check permissions:

Terminal window
ls -la ~/.credctl/config.json

The file should be 0600 (-rw-------).

Credential helper errors

AWS CLI: “Error when retrieving credentials from custom-process”

Cause: The credential_process entry in ~/.aws/config is incorrect.

Solution: Verify the entry uses an absolute path:

[profile credctl]
credential_process = /Applications/credctl.app/Contents/MacOS/credctl auth

Find the full path with:

Terminal window
which credctl

Terraform: “No valid credential sources found”

Cause: Terraform is not using the correct AWS profile.

Solution: Set the AWS_PROFILE environment variable:

Terminal window
export AWS_PROFILE=credctl
terraform plan

Or specify the profile in your Terraform provider block:

provider "aws" {
  profile = "credctl"
}

General diagnostic steps

If none of the above errors match, run through this checklist:

  1. Check version: credctl version
  2. Check device identity: credctl status
  3. Check configuration: cat ~/.credctl/config.json | python3 -m json.tool
  4. Test authentication: credctl auth
  5. Check directory permissions: ls -la ~/.credctl/
  6. Check credential_process entry: cat ~/.aws/config
  7. Verify OIDC endpoint: curl <issuer_url>/.well-known/openid-configuration

Getting help

When reporting issues, include:

  • credctl version output
  • macOS version (sw_vers)
  • The full error message
  • Steps to reproduce